New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved parsing of @tags #181

Closed
jcalfee opened this Issue Nov 25, 2015 · 3 comments

Comments

Projects
None yet
3 participants
@jcalfee

jcalfee commented Nov 25, 2015

I have some existing jsdocs and I want to use esdoc for its es6 support. I hit a snag...

It looks like the esdoc relies on the extra *s being precisely positioned. This really threw me for a while. I would suggest that the doc tags be read properly even though they are not proceeded by a star or the spacing after the star varry.

For example, this does not parse the args into a table:

/**
 *  this is object destructuring.
 *  @param {Object} param - this is object param.
 *  @param {number} param.foo - this is property param.
 *  @param {string} param.bar - this is property param.
 */
export function myFunc({ foo, bar }){}

Instead of a table, the text falls through: this is object destructuring. @param {Object} param - this is object param. @param {number} param.foo - this is property param. @param {string} param.bar - this is property param.

But this works:

/**
 * this is object destructuring.
 * @param {Object} param - this is object param.
 * @param {number} param.foo - this is property param.
 * @param {string} param.bar - this is property param.
 */
export function myFunc({ foo, bar }){}

This is not easy to figure out if the docs have other things going on (like my real test case). I would suggest that the parsing not depend on the asterisk at all. Or, at least put a warning about this in your docs.

The ideal implementation should consider many variants including this one valid :

/**
    this is object destructuring.
    @param {Object} param - this is object param.
    @param {number} param.foo - this is property param.
    @param {string} param.bar - this is property param.
 */
export function myFunc({ foo, bar }){}

In version 0.4.3

@silkentrance

This comment has been minimized.

Show comment
Hide comment
@silkentrance

silkentrance Jan 8, 2016

@jcalfee reading through the above I cannot find any difference between the provided examples. did you make sure that the markdown parser did not swallow up any relevant information?

silkentrance commented Jan 8, 2016

@jcalfee reading through the above I cannot find any difference between the provided examples. did you make sure that the markdown parser did not swallow up any relevant information?

h13i32maru added a commit that referenced this issue Feb 11, 2016

@h13i32maru

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Feb 11, 2016

Member

@jcalfee Thanks for reporting this issue. I reproduced the issue in my environment.
I fixed this issue on master

Member

h13i32maru commented Feb 11, 2016

@jcalfee Thanks for reporting this issue. I reproduced the issue in my environment.
I fixed this issue on master

@h13i32maru

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Feb 14, 2016

Member

I released v0.4.5 that fixed this issue.

Member

h13i32maru commented Feb 14, 2016

I released v0.4.5 that fixed this issue.

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