GNU bug report logs - #26550
[PATCH] Fix js.el filling inline JSDoc tags

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 26550 in the body.
You can then email your comments to 26550 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Etienne Prud'homme" <e.e.f.prudhomme <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH] Fix js.el filling inline JSDoc tags
Date: Tue, 18 Apr 2017 00:18:11 -0400

[Message part 1 (text/plain, inline)]

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

[Message part 2 (text/html, inline)]

[0001-Fix-js.el-filling-inline-JSDoc-tags.patch (text/x-patch, attachment)]

Message #8 received at 26550 <at> debbugs.gnu.org (full text, mbox):

From: "Etienne Prud'homme" <e.e.f.prudhomme <at> gmail.com>
To: 26550 <at> debbugs.gnu.org
Date: Tue, 18 Apr 2017 12:14:17 -0400

[Message part 1 (text/plain, inline)]

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.

[Message part 2 (text/html, inline)]

Message #11 received at 26550 <at> debbugs.gnu.org (full text, mbox):

From: "Etienne Prud'homme" <e.e.f.prudhomme <at> gmail.com>
To: 26550 <at> debbugs.gnu.org
Subject: Re:
Date: Wed, 19 Apr 2017 20:32:04 -0400

[Message part 1 (text/plain, inline)]

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 <e.e.f.prudhomme <at> gmail.com>:

> 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.
>

[Message part 2 (text/html, inline)]

Message #14 received at 26550 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: "Etienne Prud'homme" <e.e.f.prudhomme <at> gmail.com>
Cc: 26550 <at> debbugs.gnu.org
Subject: Re: bug#26550: [PATCH] Fix js.el filling inline JSDoc tags
Date: Mon, 24 Jun 2019 18:44:15 +0200

"Etienne Prud'homme" <e.e.f.prudhomme <at> gmail.com> writes:

> 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.

[...]

> After checking the code, it seems that having a newline inside the inline tag
> is valid [1].

Given this, the proposed change may not be the right one, so I'm closing
this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.