I've defined a custom type via #typedef:
/**
* #typedef {Object} FILE_DATA
* #property {NodeJS.ReadableStream} fileStream
* #property {string} fileUUID
*/
Then I apply this custom type in a method signature:
/**
* Upload file to Dropbox
*
* #param {FILE_DATA} fileData - file data to be stored
* #returns {Promise<Readonly<{fileName: string, folderUUID: string, isSucceeded: boolean, message: string}>>} file upload result
*/
export const fileUpload = async function fileUpload(fileData) {…}
When I generate a JSDoc, I expect that fileUpload() documentation will contain a custom type, in fact the only documentation about fileUpload() is:
(static, constant) fileUpload
Upload file to Dropbox
How to make JSDoc showing more details about fileUpload()?
To solve the issue it's important to add an annotation #function/#method to the function fleUpload:
/**
* Upload file to Dropbox
*
* #function
* #param {FILE_DATA} fileData - file data to be stored
* #returns {Promise<Readonly<{fileName: string, folderUUID: string, isSucceeded: boolean, message: string}>>} file upload result
*/
export const fileUpload = async function fileUpload(fileData) {
Once I've added this annotation, JSDoc puts fileUpload under the methods and not members.
Related
I'm trying to get jsdoc (version 3.6.7, using node 16) to turn my documented js code into actual documentation, but no matter what I do it just generates an out directory with an index.html that is primarily empty lines, rather than documentation. I've asked about this over on the issue tracker (after I searched the docs and the web for information on what one might be doing wrong to get jsdoc to generate empty files, but I can't for the life of me find anything useful that addresses that) but since it's been a few days, it feels useful to ask here as well, so that an answer in either place can be cross posted.
Running the jsdoc command does not flag any errors with the input, and completes with a normal zero exit code but generates nothing useful, so hopefully someone here's run into his before and can explain what is necessary in addition to the follow code to actually get jsdoc to generate docs.
An example of code that has no errors according to jsdoc, but also yields no docs whatsoever:
import { Errors } from "../errors.js";
import { Models } from "./models.js";
/**
* Several paragraphs of text that explain this class
*
* #class
* #namespace model
*/
export class Model {
/**
* #ignore
*/
static ALLOW_INCOMPLETE = Symbol();
/**
* Also several paragraphs explaining the use of this function.
*
* #static
* #param {*} data
* #param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
* #returns {*} a model instance
* #throws {*} one of several errors
*/
static create = function (data = undefined, allowIncomplete) {
return Models.create(
this,
data,
allowIncomplete === Model.ALLOW_INCOMPLETE
);
};
/**
* code comment that explains that if you're reading
* this source, you should not be using the constructor,
* but should use the .create factory function instead.
*
* #ignore
*/
constructor(caller, when) {
if (!caller || typeof when !== "number") {
const { name } = this.__proto__.constructor;
throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
}
}
}
Running this with jsdoc test.js yields an out dir with an index.html and test.js.html file, the first containing some thirty newlines of "no docs here" with boilerplate wrapper HTML code, and the second containing the original source code with nothing else useful either.
What else does one need to do to get jsdoc to actually generate documentation here?
I have fixed it by not using export infront of classes, instead exporting them at the end of the file. like this:
import { Errors } from "../errors.js";
import { Models } from "./models.js";
/**
* Several paragraphs of text that explain this class
*
* #class
* #namespace model
*/
class Model {
/**
* #ignore
*/
static ALLOW_INCOMPLETE = Symbol();
/**
* Also several paragraphs explaining the use of this function.
*
* #static
* #param {*} data
* #param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
* #returns {*} a model instance
* #throws {*} one of several errors
*/
static create = function (data = undefined, allowIncomplete) {
return Models.create(
this,
data,
allowIncomplete === Model.ALLOW_INCOMPLETE
);
};
/**
* code comment that explains that if you're reading
* this source, you should not be using the constructor,
* but should use the .create factory function instead.
*
* #ignore
*/
constructor(caller, when) {
if (!caller || typeof when !== "number") {
const { name } = this.__proto__.constructor;
throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
}
}
}
export {Model}
Turns out this was posted too early: taking the time to start at the official documentation for classes over on https://jsdoc.app/tags-class.html and running that example through jsdoc works perfectly fine, and subsequently building out that example to match the actual file's code yields working documentation just fine, too.
And in this specific case, there were several problems:
adding #namespace paired with #class was the main problem. Neither were necessary, but the #namespace entry changes how jsdoc parses the rest of a file's documentation, where if methods are to show up, they must use a #name property that includes that namespace. As that was not the case here, nothing ended up showing in the documentation.
having an #ignore on the constructor function, rather than using the #hideconstructor property on the class meant that even with #namespace removed, no documentation got written. JSdoc treats the class docs heading and the constructor as the same thing, so #ignoreing the constructor is treated the same as ignoring the entire class.
Fixing both mistakes, and removing the unnecessary #class at the top, gives perfectly fine documentation:
import { Errors } from "../errors.js";
import { Models } from "./models.js";
/**
* Several paragraphs of text that explain this class
*
* #hideconstructor
*/
export class Model {
/**
* #ignore
*/
static ALLOW_INCOMPLETE = Symbol();
/**
* Also several paragraphs explaining the use of this function.
*
* #static
* #param {*} data
* #param {*} allowIncomplete (must be Model.ALLOW_INCOMPLETE to do anything)
* #returns {*} a model instance
* #throws {*} one of several errors
*/
static create = function (data = undefined, allowIncomplete) {
return Models.create(
this,
data,
allowIncomplete === Model.ALLOW_INCOMPLETE
);
};
/**
* code comment that explains that if you're reading
* this source, you should not be using the constructor,
* but should use the .create factory function instead.
*/
constructor(caller, when) {
if (!caller || typeof when !== "number") {
const { name } = this.__proto__.constructor;
throw Errors.DO_NOT_USE_MODEL_CONSTRUCTOR(name);
}
}
}
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?
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 ...
};
};
});