Use of @jls in jshell

[Jonathan Gibbons]

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