RFR 8131019: jshell tool: access javadoc from tool

[Robert Field]

Thumbs up!


On October 27, 2016 7:39:33 AM Jan Lahoda <jan.lahoda at oracle.com> wrote:

> A slightly updated patch:
> http://cr.openjdk.java.net/~jlahoda/8131019/webrev.02/
>
> Changes:
> -support for modularized src.zip (SourceCodeAnalysisImpl)
> -<img> handling ("alt" attribute is printed), as suggested
> -handling for <dl>, <dt> and <dd>
>
> How does this look?
>
> Thanks,
>      Jan
>
> On 27.10.2016 04:51, Jonathan Gibbons wrote:
>> Looks OK to me.
>>
>> -- Jon
>>
>> On 10/26/2016 10:35 AM, Jan Lahoda wrote:
>>> Thanks for all the comments so far. An updated webrev reflecting the
>>> comments is here:
>>> http://cr.openjdk.java.net/~jlahoda/8131019/webrev.01/
>>>
>>> Also needs this change to the top-level repository:
>>> http://cr.openjdk.java.net/~jlahoda/8131019/toplevel.01/
>>>
>>> Summary of changes:
>>> -the text adjustment suggested by Robert
>>> -the output is paginated, and pauses after methods (if another method
>>> follows)
>>> -most of the comments below have been addressed (some more comments
>>> inlined).
>>>
>>> On 26.10.2016 04:48, Jonathan Gibbons wrote:
>>>>
>>>>
>>>> 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.
>>>
>>> Moved to:
>>> src/jdk.compiler/share/classes/jdk/internal/shellsupport/doc/resources/javadocformatter.properties
>>>
>>>
>>>>
>>>> It would be nice to provide and use String constants for the ANSI escape
>>>> sequences.
>>>
>>> Using constants now.
>>>
>>>>
>>>> JavadocFormatter.java:113 -- ex.printStackTrace seems suspect,
>>>> especially as there seems
>>>> to be better infrastructure for handling unwanted exceptions elsewhere
>>>> in JShell.
>>>
>>> Should not normally happen, I think, so I changed that to throw
>>> InternalError.
>>>
>>>>
>>>> JavadocFormatter.java:183 -- no distinguished handling for type
>>>> parameters
>>>
>>> Fixed.
>>>
>>>>
>>>> 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
>>>
>>> Using HtmlTag now.
>>>
>>>>
>>>> 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.
>>>
>>> I tried to fix the formatter so that it does not crash on broken HTML.
>>> The output may not be ideal, though.
>>>
>>>>
>>>> JavadocFormatter.java:333 -- no explicit handling for </p>
>>>
>>> Is it necessary to handle the closing tag?
>>>
>>>>
>>>> JavadocFormatter.java:444 -- suggest moving resource file
>>>> Just curious, why the CAP prefix?
>>>
>>> That's for "caption".
>>>
>>>>
>>>> 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?
>>>
>>> I've tried to fix the "tr" problem. Added tests for missing closing
>>> "td" (there were existing tests for missing closing "li").
>>>
>>>>
>>>> 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
>>>
>>> I tried to clear out the whitespaces so that these should get
>>> eliminated (but they would probably not be a big deal).
>>>
>>>>
>>>> JavadocFormatter.java
>>>>      No support for entities, including < > &
>>>
>>> Done.
>>>
>>>>
>>>> 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?
>>>
>>> Mapping from the original JavacTask to the new one is done using a
>>> "handle" (the "elementSignature" will produce a textual representation
>>> of an Element which is found in the newly parsed source). The
>>> resulting javadoc is a plain text (with @inheritDoc resolved).
>>>
>>> Any feedback is welcome.
>>>
>>> Thanks!
>>>
>>> Jan
>>>
>>>
>>>>
>>>> -- Jon
>>