Quantcast

bug#26550: [PATCH] Fix js.el filling inline JSDoc tags

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

bug#26550: [PATCH] Fix js.el filling inline JSDoc tags

Etienne Prud'homme
The attached patch fixes filling inline JSDoc tags in js-mode. JSDoc allows using tags in the form of:

> /**
>  * @foo
>  * Description. Link to other symbol {@link document.body.style}
>  * @bar

Where "@link" is the inline tag.

Currently, the paragraph starts at the "@" sign. Therefore filling the Description line would never make the "@bar" tag appear in an other column (that's what we want).

However, the link tag can be broken arbitrary and would make the tag harder to read (without considering font-lock that is implemented in an other package).

> /**
>  * @foo
>  * Description. Link to other symbol {@link
>  * document.body.style}
>  * @bar

I searched the JSDoc documentation[1] about line breaks inside an inline tags and didn't find explicit information about whether or not it was valid. Given that inline litterally means on one line, I guess we can pretend the specification doesn't allow line breaks inside an inline tag.


[1] http://usejsdoc.org/about-block-inline-tags.html

0001-Fix-js.el-filling-inline-JSDoc-tags.patch (5K) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

bug#26550:

Etienne Prud'homme
I've went ahead and submitted an issue on GitHub[1] to see if it's a
valid syntax. I would ask not to apply that patch until then. And of
course I'm always open on suggestions.

[1] https://github.com/jsdoc3/jsdoc3.github.com/issues/152

ps: I've already made the copyright assignment paperwork.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

bug#26550:

Etienne Prud'homme
After checking the code, it seems that having a newline inside the inline tag is valid [1]. However, I still think it removes clarity and it would be better to implement the patch I proposed.

[1] https://github.com/jsdoc3/jsdoc/blob/master/lib/jsdoc/tag/inline.js#L55

2017-04-18 12:14 GMT-04:00 Etienne Prud'homme <[hidden email]>:
I've went ahead and submitted an issue on GitHub[1] to see if it's a
valid syntax. I would ask not to apply that patch until then. And of
course I'm always open on suggestions.

[1] https://github.com/jsdoc3/jsdoc3.github.com/issues/152

ps: I've already made the copyright assignment paperwork.

Loading...