Use of @jls in jshell

[Robert Field]

Can't we just move the @jls tag to the end of the comment?

The "A variable declaration is..." wasn't meant to be part of the @jls tag

-Robert


On 5/30/19 1:44 PM, Jonathan Gibbons wrote:
> Joe, Robert,
>
> We recently changed the support for the @jls tag, and I note that it 
> conflicts with a style of usage that we did not detect previously with 
> line-based tools (i.e. grep.)
>
> This is one of a few similar occurrences in Snippet.java
>
>
>          * @jls 8.3 Field Declarations
>          * <P>
>          * A variable declaration is {@linkplain Kind#isPersistent() 
> persistent}.
>
> The problem is that as it currently stands, the @jls tag will detect 
> the 8.3 and then attempt to put a`<a href=...>` ... `</a>` aound the 
> rest of the content. That's bad in this case, because you can't have 
> `<P>` inside `<a>`.
>
>
> There are two ways forward:
>
> 1. Remove the extra text, and/or restructure the doc comment so that 
> the extra text is not part of @jls
>
> 2. Maybe update the @jls taglet to modify its behavior in the face of 
> more complex HTML content.
>
> My reading of the document is that these paragraphs should be moved 
> before the @jls reference, because they do not appear to be part of 
> the @jls reference.
>
> Comments, suggestions?
>
> -- Jon
>