Re: RFR: 8277847: Support toolGuide tag in class-level documentation
On Thu, 25 Nov 2021 15:58:58 GMT, Julia Boes wrote: > This change adds support for the `@toolGuide` tag in class-level API > documentation. > > (A use case is the jwebserver tool, where the > com.sun.net.httpserver.SimpleFileServer class provides API points for > extension and customization of the underlying server and its components. > Linking to the tool's man page in the class-level documentation would be > beneficial.) Extending this to allow @toolGuide be used in class descriptions is generally useful. - Marked as reviewed by alanb (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/6566
Re: RFR: 8277847: Support toolGuide tag in class-level documentation
On Thu, 25 Nov 2021 15:58:58 GMT, Julia Boes wrote:
> This change adds support for the `@toolGuide` tag in class-level API
> documentation.
>
> (A use case is the jwebserver tool, where the
> com.sun.net.httpserver.SimpleFileServer class provides API points for
> extension and customization of the underlying server and its components.
> Linking to the tool's man page in the class-level documentation would be
> beneficial.)
make/jdk/src/classes/build/tools/taglet/ToolGuide.java line 159:
> 157: .toString()
> 158: .replace('.', '/')
> 159: .replaceAll("[^/]+", "..");
If the class is in a module don't you have to get one step higher to get the
root?
I am not familiar with this code, so I'm just reasoning by induction here -
trying to match with what the case for PACKAGE seems to be doing...
-
PR: https://git.openjdk.java.net/jdk/pull/6566
Re: RFR: 8277847: Support toolGuide tag in class-level documentation
On Fri, 26 Nov 2021 11:43:25 GMT, Daniel Fuchs wrote:
>> This change adds support for the `@toolGuide` tag in class-level API
>> documentation.
>>
>> (A use case is the jwebserver tool, where the
>> com.sun.net.httpserver.SimpleFileServer class provides API points for
>> extension and customization of the underlying server and its components.
>> Linking to the tool's man page in the class-level documentation would be
>> beneficial.)
>
> make/jdk/src/classes/build/tools/taglet/ToolGuide.java line 159:
>
>> 157: .toString()
>> 158: .replace('.', '/')
>> 159: .replaceAll("[^/]+", "..");
>
> If the class is in a module don't you have to get one step higher to get the
> root?
> I am not familiar with this code, so I'm just reasoning by induction here -
> trying to match with what the case for PACKAGE seems to be doing...
Same here, I initially applied the same pattern as for PACKAGE but that does
not produce the correct path (it includes 1 ".." too much.):
String typePart = te.getQualifiedName()
.toString()
.replace('.', '/')
.replaceAll("[^/]+", "..");
return te.getEnclosingElement().getEnclosingElement() != null
? "../" + typePart
: typePart;
-
PR: https://git.openjdk.java.net/jdk/pull/6566
Re: RFR: 8277847: Support toolGuide tag in class-level documentation
On Fri, 26 Nov 2021 14:31:04 GMT, Julia Boes wrote:
>> make/jdk/src/classes/build/tools/taglet/ToolGuide.java line 159:
>>
>>> 157: .toString()
>>> 158: .replace('.', '/')
>>> 159: .replaceAll("[^/]+", "..");
>>
>> If the class is in a module don't you have to get one step higher to get the
>> root?
>> I am not familiar with this code, so I'm just reasoning by induction here -
>> trying to match with what the case for PACKAGE seems to be doing...
>
> Same here, I initially applied the same pattern as for PACKAGE but that does
> not produce the correct path (it includes 1 ".." too much.):
>
> String typePart = te.getQualifiedName()
> .toString()
> .replace('.', '/')
> .replaceAll("[^/]+", "..");
> return te.getEnclosingElement().getEnclosingElement() != null
> ? "../" + typePart
> : typePart;
I see - class has a class name which is a file - so `foo.Bar` produces `../..`
relative to the directory foo (foo/../..) - so it already has an additional
`..` compared to package - where `a.b` would produce ../.. relative to
*directory* b which would lead to `b/../..` and not `a/../..` which is what we
need.
The difference comes from the fact that `Bar` is a file whereas `b` is a
directory.
-
PR: https://git.openjdk.java.net/jdk/pull/6566
Re: RFR: 8277847: Support toolGuide tag in class-level documentation
On Thu, 25 Nov 2021 15:58:58 GMT, Julia Boes wrote: > This change adds support for the `@toolGuide` tag in class-level API > documentation. > > (A use case is the jwebserver tool, where the > com.sun.net.httpserver.SimpleFileServer class provides API points for > extension and customization of the underlying server and its components. > Linking to the tool's man page in the class-level documentation would be > beneficial.) Marked as reviewed by jjg (Reviewer). - PR: https://git.openjdk.java.net/jdk/pull/6566
