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