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.

I don't think it is impossible but I would expect that with jsdoc 3.2.2 it would be a significant undertaking. I'd expect the minimum you'd have to do is produce a custom template. I base this on the experience we've had with reorganizing the list of modules and classes put in the navigation bar: we had to create our own template. I doubt reordering methods would be easier. — Louis, Dec 19 '13 at 12:09
Thank you, I think I'll give it a try in future. Not as easy as I expected, but still may be possbile! — Anton Vernigor, Dec 19 '13 at 23:00

score 6 · Answer 1 · answered Jan 18 '17 at 15:45

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".

JSDoc preserve order of comments in output

1 Answers1