I'm a bit new to jsdocs, and I'm trying to properly document arrow functions.
Everything is fine until I add "export" at the beginning of the line, I saw multiple answers that recommended to add #module at the top and #memeberof in the documentation, but these options don't seem to work for me.
This is a sample of my code:
/** #module SampleModule */
/**
* Function description
*
* #param {string} _type - Component type.
* #param {string} currentName - Current component's name.
* #param {string} canonicalname - Current site.
* #returns {undefined}
*
* #example
*
* activateComponentWizard('t1', 'test 1', 'www.example.com')
*/
export const activateComponentWizard = async (_type, currentName, canonicalname) => { ... }
This is the result:
Any ideas what am I missing?
Related
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 }
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 }
I have a function with a huge list of options:
/**
* Show dialog in a blocking manner.
*
* #param {object} opts
* #param {string} opts.msg "Body" of the dialog.
* #param {number} opts.timeout Seconds - floating point values are rounded. (ActiveX imposes this)
* #param {string} opts.title Title of the dialog.
* #param {number} opts.icon Use constants for this. (See docs)
* #param {number} opts.buttons Use constants for this. (See docs)
* #param {number} opts.defaultButton Use constants for this. (See docs)
* #returns {number} Use our constants to check for what the user chose.
*/
const showSync = (opts) => {
...
}
But I also have a non-blocking version of this function obviously takes the same options and returns a Promise. It seems quite dirty to copy/paste the docs, as this will decrease maintainability and likelihood for accidental inconsistency.
So what would be great is something like the following:
/**
* Shows dialog in a non-blocking manner.
*
* #inheritdoc showSync
* #returns {Promise<number>} Use our constants to check for what the user chose.
*/
const show = (opts) => {
...
}
Is this possible somehow?
[UPDATE]
This is not a duplicate of JSDoc for reused Function interface because that question is merely about reusing the same definition, while this one is about reusing but also partly overwriting that definition. And hence, the answer there does not answer the question here.
I think the best way to do that with jsdoc is something like this:
/**
* Options for showing a dialog.
* #typedef {Object} ShowOptions
* #property {string} msg "Body" of the dialog.
* #property {number} timeout Seconds - floating point values are rounded. (ActiveX imposes this)
* #property {string} title Title of the dialog.
* #property {number} icon Use constants for this. (See docs)
* #property {number} buttons Use constants for this. (See docs)
* #property {number} defaultButton Use constants for this. (See docs)
*/
/**
* Show dialog in a blocking manner.
*
* #param {ShowOptions} opts
* #returns {number} Use our constants to check for what the user chose.
*/
const showSync = (opts) => {...}
/**
* Shows dialog in a non-blocking manner.
*
* #param {ShowOptions} opts
* #returns {Promise<number>} Use our constants to check for what the user chose.
*/
const show = (opts) => {...}
You could take it a step further and apply a similar concept to the return value as well:
/**
* Use our constants to check for what the user chose.
* #typedef {number} ShowResult
*/
/**
* Show dialog in a blocking manner.
*
* #param {ShowOptions} opts
* #returns {ShowResult}
*/
const showSync = (opts) => {...}
/**
* Shows dialog in a non-blocking manner.
*
* #param {ShowOptions} opts
* #returns {Promise<ShowResult>}
*/
const show = (opts) => {...}
I have jsdoc'ed my function like this:
/**
* #typedef {Object} SearchTerms
* #property {string} what
* #property {string} where
* #property {boolean} online
*/
/**
* From react-router params, which are URL encoded, it figures out the "what", "where", and "online" terms.
*
* #export
* #param {Object} params The `params` field from react-router component props.
* #param {string} [params.what="Everything"] The subject of users search.
* #param {string} [params.where] The location of users search.
* #returns {SearchTerms}
*/
export function getSearchTerms(params) {
However the params key is not properly expanded on hover of the function:
Is there anyway for it to properly expand params argument? I was hoping for it to show:
Except that it should also show that it is optional with question mark. And as I type the argument, it should show the description of that argument like this:
The problem is that you've specified the type of your params param as Object. You should break out your params as second #typedef:
/**
* #typedef SearchOptions
* #property {String} [what="Everything"] The thing
* #property {String} [where] A place
*/
/**
* #param {SearchOptions} params
*/
function getSearchTerms(params){ ... }
Using a named interface like this, VSCode should show the arguments in Intellisense like you're looking for.
How to mark or make reference function argument in jsdoc/jsdoc3.
For example:
/**
* Build xxx.
* cfg is optional.
*
* #param {Object} cfg config
* #function
*/
function build(engine, cfg) { ... }
What markup used to wrap cfg in cfg is optional. description?
I see one possible way by enclosing into tt HTML tag:
/**
* Repeat <tt>str</tt> several times.
* #param {string} str The string to repeat.
* #param {number} [times=1] How many times to repeat the string.
* #returns {string}
*/
repeat: function(str, times) { ... }
I'm brand new to JSDoc, and I'm trying to figure out the best way to tag my code. For some reason after I label something as a #class, I can't get anything to appear as #inner:
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #requires 'config/globalConfig'
*/
define(["config/globalConfig"], function (config) {
/**
* Instantiate a new copy of the logger for a class/object
* #constructor
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
/**
* #memberOf Logger
* #type {string}
*/
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function
* #memberOf Logger
* #param message {string}
*/
this.debug = function (message) {
... some code ...
};
};
});
Right now all the members are appearing as <static>. If I add the #inner tag to any of the attributes/functions they vanish completely from the output.
Edit: I also forgot to mention. The #constructor flag doesn't seem to be working either. If I remove that entire section, it appears the same in the output. The output does not include the #param that I would like to mention with my constructor.
Please let me know if this is completely off, I'm just kind of guessing here since the JSDoc3 documentation is a bit difficult to read.
So I figured it out, still not sure if it's absolutely correct. I had to use "Logger~name" to have it appear correctly as an inner function. According to the JSDoc documentation, this ~ is "rarely used". Seems to be the only thing that works for me.
define(["config/globalConfig"], function (config) {
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function Logger~debug
* #param message {string}
*/
this.debug = function (message) {
... code ...
};
};
});