Function type syntax error not handled #351

Closed
LukasHechenberger opened this Issue Nov 27, 2016 · 6 comments

Comments

Projects
None yet
3 participants
@LukasHechenberger
Contributor

LukasHechenberger commented Nov 27, 2016

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

This comment has been minimized.

Show comment
Hide comment
@typhonrt

typhonrt Nov 27, 2016

Contributor

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.

Contributor

typhonrt commented Nov 27, 2016

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

This comment has been minimized.

Show comment
Hide comment
@LukasHechenberger

LukasHechenberger Nov 27, 2016

Contributor

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.

Contributor

LukasHechenberger commented Nov 27, 2016

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

This comment has been minimized.

Show comment
Hide comment
@typhonrt

typhonrt Nov 27, 2016

Contributor

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.

Contributor

typhonrt commented Nov 27, 2016

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

This comment has been minimized.

Show comment
Hide comment
@LukasHechenberger

LukasHechenberger Nov 27, 2016

Contributor

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.

Contributor

LukasHechenberger commented Nov 27, 2016

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

This comment has been minimized.

Show comment
Hide comment
@typhonrt

typhonrt Nov 27, 2016

Contributor

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.

Contributor

typhonrt commented Nov 27, 2016

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.

LukasHechenberger added a commit to LukasHechenberger/esdoc that referenced this issue Nov 27, 2016

Better error message for invalid function type annotations
Just as an example, how better error descriptions could be implemented.
Would fix [#351](esdoc#351). Later
referencing filename and lineno would be nice

@h13i32maru h13i32maru closed this in #352 Dec 27, 2016

@h13i32maru h13i32maru added this to the next-version milestone Dec 27, 2016

@h13i32maru

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Dec 27, 2016

Member

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

Member

h13i32maru commented Dec 27, 2016

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment