RFR 8131019: jshell tool: access javadoc from tool

[Jonathan Gibbons]

On 10/17/2016 09:08 AM, Jan Lahoda wrote:
> Hello,
>
> This patch adds ability to show javadoc inside JShell (by showingg it 
> on the second invocation of the Shift-<tab> documentation). In 
> addition to jdk.jshell changes, there is a support in jdk.compiler, 
> that is expected to be reused by jjs.
>
> Bug:
> https://bugs.openjdk.java.net/browse/JDK-8131019
>
> Webrev:
> http://cr.openjdk.java.net/~jlahoda/8131019/webrev.00/
>
> Any feedback is welcome!
>
> Thanks,
>     Jan

The file 
src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javadocformatter.properties
doesn't seem like it belongs in com/sun/tools/javac/resources.

It would be nice to provide and use String constants for the ANSI escape 
sequences.

JavadocFormatter.java:113 -- ex.printStackTrace seems suspect, 
especially as there seems
to be better infrastructure for handling unwanted exceptions elsewhere 
in JShell.

JavadocFormatter.java:183 -- no distinguished handling for type parameters

JavadocFormatter.java:240 -- is it safe to assume lower case tags at 
this point?  If it helps,
you could leverage com.sun.tools.doclint.HtmlTag

JavadocFormatter.java:356 -- (general comment) what about invalid HTML 
input.
Yes, JDK javadoc comments are reasonably good these days, but that 
doesn't apply
everywhere.

JavadocFormatter.java:333 -- no explicit handling for </p>

JavadocFormatter.java:444 -- suggest moving resource file
Just curious, why the CAP prefix?

JavaDocFormatter.java:visitEndElement: it is common to see optional end 
tags omitted, like
     </li>, </td>, </tr>
     This could screw up the stacks. If </tr> is omitted, won't you skip 
printing the row?

JavadocFormatter.java:409
     Ignoring </td>, </th> will mean that vertical whitespace between 
table cell elements
     may be incorporated into the table cell itself, won't it?  I guess 
in general, it'll all be
     collapsed into a space character, so in general you'll be OK

JavadocFormatter.java
     No support for entities, including < > &

JavadocHelper.java
     I haven't figured out how the {@inheritDoc} resolver is working, 
insofar as how are you
     working with the issue that you have to create a new JavacTask for 
each tree that you
     parse, which means separate distinct components like Names, Symtab, 
and all the other
     javac internal classes. In particular, when you start computing 
supertypes, how do
     you coordinate the different elements provided by the different 
JavacTask objects?

-- Jon