RFR 8131019: jshell tool: access javadoc from tool

Tue Nov 1 16:44:00 UTC 2016

Sure, will do.

Jan

On 1.11.2016 16:18, Robert Field wrote:
> 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
>>>>
>