I would like to keep inline ments as short as possible, since my experience is that ments of more than 3 or 4 lines tend to be glossed over, creating a lot of unnecessary "read the manual lines".

I'm required by legacy to adhere to a jsdoc-patible format for documenting code. It requires that a lot of self evident things be declared explicitly if they're to be documented correctly. Practically every tag can fall in this category. Even the ones that don't are often useless to a working developer.

My vision is to have a quick summary inside the code itself that developers will actually read, but refer to a separate file (or even a ment dump in the same file, separate from where developers will be working) for additional tagging, like this:

/**
 *  Used when making an example of the argument.
 *  @include someotherplace
 */
function example(argument) { stuff;}

...lots more code...

/**
 *  someotherplace
 *  @param argument The victim
 *  @since forever
 *  @other stuff
 */

A different tool or a plugin would be acceptable, I'm really only stuck with the syntax. Another alternative would be a tool with some really good implicit documentation creation

I would like to keep inline ments as short as possible, since my experience is that ments of more than 3 or 4 lines tend to be glossed over, creating a lot of unnecessary "read the manual lines".

I'm required by legacy to adhere to a jsdoc-patible format for documenting code. It requires that a lot of self evident things be declared explicitly if they're to be documented correctly. Practically every tag can fall in this category. Even the ones that don't are often useless to a working developer.

My vision is to have a quick summary inside the code itself that developers will actually read, but refer to a separate file (or even a ment dump in the same file, separate from where developers will be working) for additional tagging, like this:

/**
 *  Used when making an example of the argument.
 *  @include someotherplace
 */
function example(argument) { stuff;}

...lots more code...

/**
 *  someotherplace
 *  @param argument The victim
 *  @since forever
 *  @other stuff
 */

A different tool or a plugin would be acceptable, I'm really only stuck with the syntax. Another alternative would be a tool with some really good implicit documentation creation

• javascript
• documentation-generation
• jsdoc

• Which version of jsdoc are you using? There are significant differences between jsdoc 2 and jsdoc 3. – Louis Commented Nov 18, 2013 at 12:21
• I'll use whichever version solves my problem, but 3 would be preferred on the grounds that it's still active. – user2999782 Commented Nov 18, 2013 at 20:40
• Typescript lets you store the argument types in a separate file. Maybe it will let you document them there too. – joeytwiddle Commented Apr 11, 2016 at 10:54

3 Answers 3

With jsdoc3, I do not think there is a way to get what a perfect solution without having to write a new plugin. (I do not know of a plugin that would already do it.)

However, it is possible to abuse the jsdoc tags to get something which is not perfect but is functional.

/**
 * @module foo
 */


/**
 * Used when making an example of the argument.
 * @see {module:foo.example_type}
 */
function example(argument) {
    //...
}

/**
 * someotherplace
 * @typedef {function} module:foo.example_type
 * @param argument The victim
 * @since forever
 */

The key is to create a type definition with a unique name, and then use @see to link to that definition. @module and module: are just there to show it can be done with modules. They can just be stripped for cases where modules are not needed.

What about {@link} tag and tutorials {@tutorial} tags? From documentation:

{@tutorial} Tutorials

Tutorials mechanism allows you to include not only short code-related technical API documentation, but also longer, more explaining, full-page tutorials

The {@link} tag allows you to create a HTML link to some other documented symbol from within the text of any tag's description.

Usage:

@anyTag This is some text {@link otherSymbol}.

I am using vscode and typescript and discovered that you just need to import the function/variable you want to reference and the link starts working:

/**
 * @deprecated Use {@link func} instead
 */
const func_deprecated = () => {}