JSDoc preserve order of comments in output

Question

I have a JavaScript object, that introduces some public methods and I want to use JSDoc to document them.

In the source file I have these functions grouped and ordered in a reasonable order, but after generating JSDoc I receive all of them in an alphabetical order, that doesn't make much sense.

Is there any way to keep the order in the output? I couldn't find any answer, but I also couldn't find that it's impossible.

Answer 1

The short answer:

Within your conf.json file, add an opts element of "sort": false, where sort is flagging whether JSDoc should use alphabetical sorting.

Assuming you are using a conf.json file to designate your JSDOC configuration options:

jsdoc -c path/to/conf.json

For example:

{
    "tags": {
        "allowUnknownTags": false
    },
    "source": {
        "includePattern": ".+\\.js(doc)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": false,
    },
    "opts": {
        "encoding": "utf8",
        "lenient": false,
        "sort": false
    }
}

I also came across Docstrap, a Bootstrap template for JSDoc3.

You can then use the 'sort' option within the templates section. Example of a conf.json file for this case might appear as:

{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
        "sort": false
    }
}

The description given from the Docstrap site is:

sort Defaults to true. Specifies whether jsdoc should sort data or use file order. Can also be a string and if so it is passed to jsdoc directly. The default string is "longname, version, since".