Function type syntax error not handled

[LukasHechenberger]

If a function type annotation is missing a parameter label an error is thrown from the DocBuilder class.
Of course, this is my fault, but it would be very nice if the error message contained the failing file or even better the invalid annotation. Currently I'm receiving the following output:

// Source.js
/**
 * Removes the item with the specified id.
 * @param {Number} id Id of the item to be removed.
 * @param {function(Error, removed: Number)} callback Called with the number of items removed.
 */
removeItem(id, callback) { ... }

(The callback parameter is missing a label for the Error argument)

.../node_modules/esdoc/out/src/Publisher/Builder/ClassDocBuilder.js:79
            throw _iteratorError;
            ^

TypeError: Cannot read property 'replace' of undefined
    at .../node_modules/esdoc/out/src/Publisher/Builder/DocBuilder.js:924:34
    at Array.map (native)
    at ClassDocBuilder._buildTypeDocLinkHTML (.../node_modules/esdoc/out/src/Publisher/Builder/DocBuilder.js:919:41)
    at ClassDocBuilder._buildSignatureHTML (.../node_modules/esdoc/out/src/Publisher/Builder/DocBuilder.js:1156:33)
    at .../node_modules/esdoc/out/src/Publisher/Builder/DocBuilder.js:512:38
    at IceCap.loop (/Users/lukas/Documents/Partypics/Code/API/node_modules/ice-cap/out/src/IceCap.js:261:9)
    at ClassDocBuilder._buildSummaryDoc (.../node_modules/esdoc/out/src/Publisher/Builder/DocBuilder.js:509:11)
    at ClassDocBuilder._buildSummaryHTML (.../node_modules/esdoc/out/src/Publisher/Builder/DocBuilder.js:468:29)
    at ClassDocBuilder._buildClassDoc (.../node_modules/esdoc/out/src/Publisher/Builder/ClassDocBuilder.js:167:38)
    at ClassDocBuilder.exec (.../node_modules/esdoc/out/src/Publisher/Builder/ClassDocBuilder.js:64:36)

It was really hard to find out where the error occurred because I'm working on a really large project.

[typhonrt]

Yeah.. There needs to be better error resolution with softer failures and descriptive reporting for which files that have problems. This comes up fairly often, re: #335 for instance in most of the errors reported generally. I don't think there is a specific issue filed that addresses better error output.

The present output certainly is useful to find the error, but that kind of output should only be enabled by a flag or config option w/ the sanitized version for default.

[LukasHechenberger]

Thanks for the fast reply!
Are there any plans to implement those more descriptive error reports? Otherwise I could try to do this... I really like and heavily rely on ESDoc so I'd love to help improving it.

[typhonrt]

If I had any control I'd put it in right away. I also heavily rely on ESDoc and have done tons of plugin development.

You'll see this in other comments as I guess I'm not really holding back anymore... The biggest problem per se is that ESDoc is run by a sole maintainer from Japan who doesn't always come around to communicate and is absent for stretches at a time. Bless his heart for the initial creation, but it's been seemingly treated as a hobby / curiosity for quite some time. A supposed new version is partially being worked on, but it's been way too long. See #293... To make things a bit silly this more or less was in response to my announcement of a major fork after much stagnation for the first half of the year which adds a bunch of new functionality re: #292 of which all the meat is moving to Babylon behind the scene. It should take no more than a week to accomplish #293, but here we are almost 5 months later with no idea on when things will be updated. I'm trying to give the maintainer the chance to release v1.0, but a permanent fork of ESDoc that receives rapid feature development and is more open to collaborators is likely necessary.

Your PR will likely sit there and be unattended for quite some time and perhaps rejected. As things go this kind of fix is kind of a core design decision as well, so a bit more of a touchy subject as it goes for a new contribution. It's kind of a two part problem for the full solution.

[LukasHechenberger]

Okay, thanks for the update. I think I'm going to create a PR anyway, just to show we really need improved error reports. I'll stay up to date with your work on ESDoc, thank you for keeping this project alive or at least trying to do so.

[typhonrt]

Most definitely give it a go.

I'm still hopeful that the maintainer will open it up to accepting collaborators after v1.0 as sort of hinted at, but I'm pretty much going to draw the line if things aren't complete for the official v1.0 by the new year or thereabout and then proceed forward.

[h13i32maru]

@LukasHechenberger Thanks PR 😄
And I also fixed it.
c7c2596