Documenting inner method of function expression with jsDoc 3.6.6 - Intellisense works but jsdoc doesn't

Question

I want to document a function expression from some example Alexa SDK code. This person seems to know what they're doing, except the jsdoc linter doesn't like the inline import like this: @param {import('ask-sdk-core').HandlerInput} handlerInput

so I just used the standard require at top of file workaround. const { HandlerInput } = require('ask-sdk-core') and then inline: @param {HandlerInput} handlerInput - blah

Intellisense loves it, everything seems great...

except JSDOC gives me nothing:

I seem to have all other aspects of jsdoc working perfectly and everything documents beautifully. Except this. I have tried referencing the constant as almost every type, scoured github, read things link the following: JSDoc not recognizing exported function JSDOC: How to document inner variables of function

Here's a slimmed down abridged version of the example code I linked to above. What have I missed or got wrong? Any ideas appreciated. Thanks.

const { HandlerInput } = require('ask-sdk-core')

/** @constant */
const audioController = {
  /**
   * Handles the creation of a response with an AudioPlayerPlayDirective, relying on previously set playbackInfo values. Also updates certain appSettings to maintain correct state of the skill.
   *
   * @param {HandlerInput} handlerInput - defined by Alexa
   * @returns {Promise<HandlerInput.Response>} alexa response object
   */
  async play (handlerInput) {
    const speakOutput = 'playing'
    return handlerInput.responseBuilder.speak(speakOutput).getResponse()
  },
  /**
   * Handles the creation of a response with an AudioPlayerStopDirective
   *
   * @param {HandlerInput} handlerInput - defined by Alexa
   * @returns {object} alexa response object
   */
  stop (handlerInput) {
    const speakOutput = 'stopping'
    return handlerInput.responseBuilder.speak(speakOutput).getResponse()
  }
}
module.exports = { audioController }

[...]inner method of a function expression[...] — this doesn't make much sense. Which method of which function expression are you talking about? I can't see any. Your audioController variable looks more like a namespace. I'd replace @constant with @namespace. — customcommander
Thank you for your answer @customcommander. The terminology I used was from reading other questions about jsdoc. Your guidance helped me figure it out and I've posted an answer which seems to work for both jsdoc AND intellisense. Many thanks, — digitaltoast

digitaltoast digitaltoast · Accepted Answer · 2021-02-28T10:02:43

Thanks to @customcommander for the guidance, I was then able to find this Q&A which pointed me towards the following solution. Unfortunately, VSCode intellisense doesn't "see" namespace definitions in separate files, although jsdoc has no problem.

It seems like jsdoc doesn't require @memberof, but from what I can find it's good practice(?) and does no harm. Many thanks for the help.

/**
 * Audiocontroller namespace
 *
 * @namespace audioController
 */
const audioController = {
  /**
   * Handles the creation of a response with an AudioPlayerPlayDirective
   *
   * @param {HandlerInput} handlerInput - defined by Alexa
   * @memberof audioController
   * @returns {object} alexa response object
   */
  async play (handlerInput) {
    const speakOutput = 'playing'
    return handlerInput.responseBuilder.speak(speakOutput).getResponse()
  },
  /**
   * Handles the creation of a response with an AudioPlayerStopDirective
   *
   * @param {HandlerInput} handlerInput - defined by Alexa
   * @memberof audioController
   * @returns {object} alexa response object
   */
  stop (handlerInput) {
    const speakOutput = 'stopping'
    return handlerInput.responseBuilder.speak(speakOutput).getResponse()
  }
}

module.exports = { audioController }

Documenting inner method of function expression with jsDoc 3.6.6 - Intellisense works but jsdoc doesn't

1 Answers