RFR 8131019: jshell tool: access javadoc from tool

[Robert Field]

New doc looks good.

+         * @return the javadoc, or null if not found

Maybe this should be seomthing like:   ... or null if not found or not 
requested

-Robert


On 11/01/16 05:59, Jan Lahoda wrote:
> An updated webrev that tweaks the javadoc for the 
> SourceCodeAnalysis.documentation method (no other changes):
> http://cr.openjdk.java.net/~jlahoda/8131019/webrev.03/
>
> http://cr.openjdk.java.net/~jlahoda/8131019/webrev.03/src/jdk.jshell/share/classes/jdk/jshell/SourceCodeAnalysis.java.udiff.html 
>
>
> How does that look?
>
> Thanks,
>     Jan
>
> On 27.10.2016 16:39, Jan Lahoda 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
>>>