@throws annotations not rendered correctly

[fasttime]

I'm not sure where this belongs, so I'm going to post here. I have this .js file:

/**
 * @function
 * @throws {ReferenceError}
 * @throws {SyntaxError} Syntax error
 * @throws Another error, too.
 */
function foo () { }

The output of jsdoc-parse looks so:

[
  {
    "kind": "function",
    "exceptions": [
      {
        "type": {
          "names": [
            "ReferenceError"
          ]
        }
      },
      {
        "type": {
          "names": [
            "SyntaxError"
          ]
        },
        "description": "Syntax error"
      },
      {
        "description": "Another error, too."
      }
    ],
    "type": {
      "names": [
        "ReferenceError"
      ]
    },
    "description": "Syntax error",
    "name": "foo",
    "longname": "foo",
    "scope": "global",
    "codeName": "foo"
  }
]

This is ok except that "ReferenceError" is repeated outside "exceptions". Then dmd gives this output:

<a name="foo"></a>
#foo()
Syntax error

**Type**: `ReferenceError`  

Here one exception is rendered in place of the function description, one has the caption "Type", and another one is gone.

I'm working on a project that uses grunt-jsdoc-to-markdown to generate the documentation for the function reference, and this is an example of a real file where the problem occurs: https://github.com/fasttime/Q-exact/blob/49f3daf0c2905e828c3544b1c16e6a518dd4c31f/lib/q.js (@throws annotation in constructor).

[75lb]

yep, you've found a bug.. however, i'm very close to releasing a new version of the tool.. i have generated docs for your project using the new version, how does it look? https://github.com/75lb/Q-exact/blob/master/docs.md

[fasttime]

Wow, the new look is cool :-) The throws annotation is also ok. :+1: I've noticed that the members are shuffled now (in the member list and also in the document). If you could fix that before the release it would be great. Thanks and keep up the good job!

[75lb]

ah, yes - i fixed the sorting.. thanks..

[fasttime]

Hi again, just wanted to say that I removed the @throws annotations from my comments now. If you wish to test your new version with those annotations as they would appear in the Q-exact reference once they work well, here's a branch where I'm using them (in place of my current workaround :-) - https://github.com/fasttime/Q-exact/blob/throws/lib/q.js

[75lb]

i generated your docs from the throws branch, how's it looking? https://github.com/75lb/Q-exact/blob/throws/Q-exact.md

install the next version preview: $ npm install -g jsdoc-to-markdown@next

then try it for yourself: $ jsdoc2md --heading-depth 1 lib/q.js --sort-by scope,kind > Q-exact.md

take a look at the new options: $ jsdoc2md --help

[fasttime]

Thanks! I followed your instructions to build the doc and it worked like a charm: https://github.com/fasttime/Q-exact/blob/throws/Q-exact.md

Now the function names are sorted alphabetically in Global and in the class member index but they're still scrambled in the document below. I hope this won't be too much work to fix, too.

Another thing is that markdown syntax doesn't work well in <dl> tags. So I had some automatically generated links in the Global section that looked like Q rather than Q because of the enclosing <dd>. When I run jsdoc2md with --global-index-format list or --global-index-format table everything looks ok.

[75lb]

thanks for the feedback :)

do a reinstall and try again $ npm install -g jsdoc-to-markdown@next

this command $ jsdoc2md lib/q.js > Q-exact.md

should produce this (with the sorting and dl list links fixed) https://github.com/75lb/Q-exact/blob/throws/Q-exact.md

any more issues, let me know! your criticism and feedback is very useful :+1:

[fasttime]

Happy to help :-) I don't see any other issues. Everything's perfect now :+1: I'll keep watching this and update my project when you decide to release the new version with a Grunt plugin. Just ping me if there's more I can do.