In JSDoc, what is the correct definition of doclet?

user_16418839 0
Viewed 105
//Example 1
/**
 * This is a function that return a message
 * @param {String} msg The message that gonna be returned
 * @returns {String} The message 
 */
function myFunction(msg) {
  return msg
}

//Example 2
/**
 * This is a function that return a message
 * @function myFunction
 * @param {String} msg The message that gonna be returned
 * @returns {String} The message 
 */

Take the examples above, can you guys tell me which is exactly a doclet in JSDoc? The comment that "rely" on a function to display on documentation (example 1) or the one displays on the documentation without "rely" on anything (Because i give it its own name which is myFunction)?

jsdoc javascript
1 Answers

A doclet is a JSDoc entity exposed to plugins and templates. Most people deal with JSDoc annotations instead e.g.,

so.js

/**
 * This is a JSDoc comment
 */

Dumping the doclets:

# npx jsdoc -X so.js
[
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/so.js"
        ]
    }
]

Another example:

/**
 * @return {boolean}
 */
function foo() {
  return true;
}

Doclets:

# npx jsdoc -X so.js 
[
    {
        "comment": "/**\n * @return {boolean}\n */",
        "meta": {
            "range": [
                29,
                62
            ],
            "filename": "so.js",
            "lineno": 4,
            "columnno": 0,
            "path": "/workspace/dev/tmp",
            "code": {
                "id": "astnode100000002",
                "name": "foo",
                "type": "FunctionDeclaration",
                "paramnames": []
            }
        },
        "returns": [
            {
                "type": {
                    "names": [
                        "boolean"
                    ]
                }
            }
        ],
        "name": "foo",
        "longname": "foo",
        "kind": "function",
        "scope": "global",
        "params": []
    },
    {
        "kind": "package",
        "longname": "package:undefined",
        "files": [
            "/workspace/dev/tmp/so.js"
        ]
    }
]

As you can see JSDoc didn't need you to say that foo is a function. There's a lot of information that can be inferred from the source code and that information is captured in a doclet.

There are a few places in the JSDoc documentation mentioning "virtual JSDoc comment". These are standalone JSDoc blocks i.e. not immediately followed by JS code. In fact you could generate an entire API documentation with just virtual JSDoc comments and no actual code at all.

user_12448840
Related