From jonathan.gibbons at oracle.com  Wed May  2 18:23:30 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 2 May 2018 11:23:30 -0700
Subject: Public API for programmatic registration of Taglet?
In-Reply-To: <2346480b-fcf0-477e-5cf1-7288d117e32f@geomatys.com>
References: <2346480b-fcf0-477e-5cf1-7288d117e32f@geomatys.com>
Message-ID: <571d2448-1df0-3adf-afc4-7cf5240a8ed0@oracle.com>

FYI, the Taglet.init issue has been addressed.

https://bugs.openjdk.java.net/browse/JDK-8201817

The issue about programmatic registration (addCustomTag) is still under 
investigation.

-- Jon


On 4/18/18 9:08 AM, Martin Desruisseaux wrote:
>
> Hello
>
> I'm trying to write an extension of the standard doclet together with 
> custom taglets in the same JAR file. The custom taglets and doclet 
> need to share information. But I faced the following difficulties:
>
> When the Taglet.init?(DocletEnvironment,Doclet) method is invoked, the 
> doclet argument given by the caller is the internal HtmlDoclet wrapped 
> by StandardDoclet, not my custom StandardDoclet subtype. So I can not 
> get my doclet and taglet in touch that way.
>
> The lazy workaround - shared static fields - does not work because the 
> taglet is loaded in a different class loader than the doclet. So even 
> if I change a static field value from the taglet, the doclet never see 
> that change. This is not a multi-threading issue; I tested with 
> volatile static field. I also verified that the class loaders for the 
> same class were different depending on whether the class of my JAR 
> file is accessed from the doclet or from the taglet.
>
> I tried to wrap DocletEnvironment in order to return a customised 
> ForwardingJavaFileManager, in an attempt to control which ClassLoader 
> is used for loading the taglet. But the standard doclet does not seem 
> to accept customized DocletEnvironment, as suggested by the error that 
> I got:
>
>     java.lang.ClassCastException: org.opengis.tools.doclet.ForwardingDocletEnvironment cannot be cast to jdk.javadoc/jdk.javadoc.internal.tool.DocEnvImpl
>      ??????? at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.WorkArounds.<init>(WorkArounds.java:101)
>      ??????? at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:108)
>      ??????? at jdk.javadoc/jdk.javadoc.doclet.StandardDoclet.run(StandardDoclet.java:72)
>      ??????? (...snip...)
>
> The jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager class 
> has public void addCustomTag(Taglet) method which seems perfect for my 
> need, but I found no public API for accessing this functionality.
>
> Is there a public way for a doclet to know its registered taglets, or 
> any other workaround that I may have missed? If not, would the 
> following evolution of Javadoc tools be possible?
>
>   * When extending the StandardDoclet, the doclet given in
>     Taglet.init(...) method should be the user StandardDoclet instance
>     instead than the JDK internal HtmlDoclet.
>   * Alternatively, a public API for addCustomTag(?) functionality
>     would also work.
>
> Regards,
>
> ??? Martin
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180502/155ca5cc/attachment.html>

From martin.desruisseaux at geomatys.com  Wed May  2 19:44:05 2018
From: martin.desruisseaux at geomatys.com (Martin Desruisseaux)
Date: Wed, 2 May 2018 21:44:05 +0200
Subject: Public API for programmatic registration of Taglet?
In-Reply-To: <571d2448-1df0-3adf-afc4-7cf5240a8ed0@oracle.com>
References: <2346480b-fcf0-477e-5cf1-7288d117e32f@geomatys.com>
 <571d2448-1df0-3adf-afc4-7cf5240a8ed0@oracle.com>
Message-ID: <31979e98-cb1a-6781-ed72-35941de9951a@geomatys.com>

Thanks!

In the main time (just in case it may be of some use to someone), below
is the workaroud I applied in order to find the primary Doclet class:

    @Override
    public void init(final DocletEnvironment env, final jdk.javadoc.doclet.Doclet doclet) {
        StackWalker.getInstance(StackWalker.Option.RETAIN_CLASS_REFERENCE).walk(stream ->
                stream.filter(frame -> frame.getClassName().equals("mypackage.MyDoclet"))
                      .map(frame -> frame.getDeclaringClass()).findFirst()).ifPresent(c -> init(c));
    }

    /**
     * Invoked with the primary doclet class.
     * This is not MyDoclet.class because of different ClassLoader.
     */
    protected void init(final Class<?> doclet) {
        // Invoke some method using reflection.
    }

??? Martin

Le 02/05/2018 ? 20:23, Jonathan Gibbons a ?crit?:

> FYI, the Taglet.init issue has been addressed.
>
> https://bugs.openjdk.java.net/browse/JDK-8201817
>
> The issue about programmatic registration (addCustomTag) is still
> under investigation.
>
> -- Jon
>


From jonathan.gibbons at oracle.com  Wed May  2 19:46:39 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 02 May 2018 12:46:39 -0700
Subject: Public API for programmatic registration of Taglet?
In-Reply-To: <31979e98-cb1a-6781-ed72-35941de9951a@geomatys.com>
References: <2346480b-fcf0-477e-5cf1-7288d117e32f@geomatys.com>
 <571d2448-1df0-3adf-afc4-7cf5240a8ed0@oracle.com>
 <31979e98-cb1a-6781-ed72-35941de9951a@geomatys.com>
Message-ID: <5AEA159F.8050004@oracle.com>

Very nice workaround.

-- Jon

On 05/02/2018 12:44 PM, Martin Desruisseaux wrote:
> Thanks!
>
> In the main time (just in case it may be of some use to someone), below
> is the workaroud I applied in order to find the primary Doclet class:
>
>      @Override
>      public void init(final DocletEnvironment env, final jdk.javadoc.doclet.Doclet doclet) {
>          StackWalker.getInstance(StackWalker.Option.RETAIN_CLASS_REFERENCE).walk(stream ->
>                  stream.filter(frame -> frame.getClassName().equals("mypackage.MyDoclet"))
>                        .map(frame -> frame.getDeclaringClass()).findFirst()).ifPresent(c -> init(c));
>      }
>
>      /**
>       * Invoked with the primary doclet class.
>       * This is not MyDoclet.class because of different ClassLoader.
>       */
>      protected void init(final Class<?> doclet) {
>          // Invoke some method using reflection.
>      }
>
>      Martin
>
> Le 02/05/2018 ? 20:23, Jonathan Gibbons a ?crit :
>
>> FYI, the Taglet.init issue has been addressed.
>>
>> https://bugs.openjdk.java.net/browse/JDK-8201817
>>
>> The issue about programmatic registration (addCustomTag) is still
>> under investigation.
>>
>> -- Jon
>>


From martin.desruisseaux at geomatys.com  Mon May 14 10:31:23 2018
From: martin.desruisseaux at geomatys.com (Martin Desruisseaux)
Date: Mon, 14 May 2018 12:31:23 +0200
Subject: Behavioural change of {@code} regarding Unicode characters?
Message-ID: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>

Hello

I noticed a behavioural change of {@code} inline tag with Java 10. In
Java versions 5 to 8, text inside {@code} was rendered literally,
including Unicode characters outside ASCII range. But in Java 10,
Unicode characters are replaced by the "\u" escape sequence. For example:

    {@code foo(?)}

Was rendered as foo(?) in HTML javadoc generated by Java 8, but is now
rendered as foo(\u2026) in javadoc generated by Java 10. Is this
behavioural change intentional? I do not see notice about handling of
Unicode characters in [1].

??? Martin

P.S.: in the documentation about {@literal}, the link to the {@code} tag
at the end of the paragraph actually references {@link}.

[1] https://docs.oracle.com/javase/10/docs/specs/doc-comment-spec.html#code
[2] https://docs.oracle.com/javase/10/docs/specs/doc-comment-spec.html#literal

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180514/985ea303/attachment.html>

From jonathan.gibbons at oracle.com  Mon May 14 14:58:40 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 14 May 2018 07:58:40 -0700
Subject: Behavioural change of {@code} regarding Unicode characters?
In-Reply-To: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>
References: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>
Message-ID: <de164ae4-b733-8bcf-6ac6-b6cdc7e1a1e0@oracle.com>

Martin,

Thanks for the report; there is no intentional change in this area.

Can you give a specific example of a comment containing {@code} that 
illustrates the issue, showing the exact representation of the Unicode 
character?

I'll check out the doc comment spec, and fix the issue you mention.

-- Jon


On 5/14/18 3:31 AM, Martin Desruisseaux wrote:
>
> Hello
>
> I noticed a behavioural change of {@code} inline tag with Java 10. In 
> Java versions 5 to 8, text inside {@code} was rendered literally, 
> including Unicode characters outside ASCII range. But in Java 10, 
> Unicode characters are replaced by the "\u" escape sequence. For example:
>
>     {@code foo(?)}
>
> Was rendered as foo(?) in HTML javadoc generated by Java 8, but is now 
> rendered as foo(\u2026) in javadoc generated by Java 10. Is this 
> behavioural change intentional? I do not see notice about handling of 
> Unicode characters in [1].
>
> ??? Martin
>
> P.S.: in the documentation about {@literal}, the link to the {@code} 
> tag at the end of the paragraph actually references {@link}.
>
> [1]https://docs.oracle.com/javase/10/docs/specs/doc-comment-spec.html#code
> [2]https://docs.oracle.com/javase/10/docs/specs/doc-comment-spec.html#literal
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180514/ca2af7fd/attachment.html>

From jonathan.gibbons at oracle.com  Mon May 14 16:15:14 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 14 May 2018 09:15:14 -0700
Subject: Behavioural change of {@code} regarding Unicode characters?
In-Reply-To: <4a37fde7-4168-8820-272c-0071311ece0c@geomatys.com>
References: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>
 <de164ae4-b733-8bcf-6ac6-b6cdc7e1a1e0@oracle.com>
 <4a37fde7-4168-8820-272c-0071311ece0c@geomatys.com>
Message-ID: <f8549383-f410-afde-cde3-0eeb4d15b43d@oracle.com>

Thanks. And, wow!? I'll investigate.

-- Jon


On 5/14/18 8:41 AM, Martin Desruisseaux wrote:
>
> Hello Jonathan
>
> Le 14/05/2018 ? 16:58, Jonathan Gibbons a ?crit?:
>
>> Can you give a specific example of a comment containing {@code} that 
>> illustrates the issue, showing the exact representation of the 
>> Unicode character?
>
> Attached is an example reproducing the issue. The Java source file 
> uses UTF-8 encoding. Steps to reproduce (assuming UTF-8 is the system 
> default encoding):
>
>     javac Code.java
>     javadoc -charset UTF-8 Code.java
>
> Then open the Code.html generated file. The page shows:
>
>     Hello World(\u2026).
>
> while the expected result is:
>
>     Hello World(?).
>
> The same test with Java 8 shows the expected results.
>
> Regards,
>
> ??? Martin
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180514/2895926b/attachment.html>

From martin.desruisseaux at geomatys.com  Mon May 14 15:41:09 2018
From: martin.desruisseaux at geomatys.com (Martin Desruisseaux)
Date: Mon, 14 May 2018 17:41:09 +0200
Subject: Behavioural change of {@code} regarding Unicode characters?
In-Reply-To: <de164ae4-b733-8bcf-6ac6-b6cdc7e1a1e0@oracle.com>
References: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>
 <de164ae4-b733-8bcf-6ac6-b6cdc7e1a1e0@oracle.com>
Message-ID: <4a37fde7-4168-8820-272c-0071311ece0c@geomatys.com>

Hello Jonathan

Le 14/05/2018 ? 16:58, Jonathan Gibbons a ?crit?:

> Can you give a specific example of a comment containing {@code} that
> illustrates the issue, showing the exact representation of the Unicode
> character?

Attached is an example reproducing the issue. The Java source file uses
UTF-8 encoding. Steps to reproduce (assuming UTF-8 is the system default
encoding):

    javac Code.java
    javadoc -charset UTF-8 Code.java

Then open the Code.html generated file. The page shows:

    Hello World(\u2026).

while the expected result is:

    Hello World(?).

The same test with Java 8 shows the expected results.

Regards,

??? Martin


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180514/cbeb180e/attachment.html>
-------------- next part --------------
/**
 * Hello {@code World(?)}.
 */
public class Code {
}

From jonathan.gibbons at oracle.com  Mon May 14 20:29:00 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 14 May 2018 13:29:00 -0700
Subject: Behavioural change of {@code} regarding Unicode characters?
In-Reply-To: <f8549383-f410-afde-cde3-0eeb4d15b43d@oracle.com>
References: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>
 <de164ae4-b733-8bcf-6ac6-b6cdc7e1a1e0@oracle.com>
 <4a37fde7-4168-8820-272c-0071311ece0c@geomatys.com>
 <f8549383-f410-afde-cde3-0eeb4d15b43d@oracle.com>
Message-ID: <5AF9F18C.9070603@oracle.com>

Martin,

Thanks again for the report and small test case.  This is being tracked as:
https://bugs.openjdk.java.net/browse/JDK-8203176

Cause Known; fix may require some consideration.

-- Jon

On 05/14/2018 09:15 AM, Jonathan Gibbons wrote:
>
> Thanks. And, wow!  I'll investigate.
>
> -- Jon
>
>
> On 5/14/18 8:41 AM, Martin Desruisseaux wrote:
>>
>> Hello Jonathan
>>
>> Le 14/05/2018 ? 16:58, Jonathan Gibbons a ?crit :
>>
>>> Can you give a specific example of a comment containing {@code} that 
>>> illustrates the issue, showing the exact representation of the 
>>> Unicode character?
>>
>> Attached is an example reproducing the issue. The Java source file 
>> uses UTF-8 encoding. Steps to reproduce (assuming UTF-8 is the system 
>> default encoding):
>>
>>     javac Code.java
>>     javadoc -charset UTF-8 Code.java
>>
>> Then open the Code.html generated file. The page shows:
>>
>>     Hello World(\u2026).
>>
>> while the expected result is:
>>
>>     Hello World(?).
>>
>> The same test with Java 8 shows the expected results.
>>
>> Regards,
>>
>>     Martin
>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180514/4f2e57b7/attachment-0001.html>

From martin.desruisseaux at geomatys.com  Mon May 14 20:35:59 2018
From: martin.desruisseaux at geomatys.com (Martin Desruisseaux)
Date: Mon, 14 May 2018 22:35:59 +0200
Subject: Behavioural change of {@code} regarding Unicode characters?
In-Reply-To: <5AF9F18C.9070603@oracle.com>
References: <87e0e198-9a66-cd49-d372-ffbbc505c41b@geomatys.com>
 <de164ae4-b733-8bcf-6ac6-b6cdc7e1a1e0@oracle.com>
 <4a37fde7-4168-8820-272c-0071311ece0c@geomatys.com>
 <f8549383-f410-afde-cde3-0eeb4d15b43d@oracle.com>
 <5AF9F18C.9070603@oracle.com>
Message-ID: <f8825358-0061-1c4f-5ec1-a9c05b593f9c@geomatys.com>

Thanks for this quick investigation!

??? Martin


Le 14/05/2018 ? 22:29, Jonathan Gibbons a ?crit?:

> Martin,
>
> Thanks again for the report and small test case.? This is being
> tracked as:
> https://bugs.openjdk.java.net/browse/JDK-8203176
>
> Cause Known; fix may require some consideration.
>
> -- Jon


From jonathan.gibbons at oracle.com  Thu May 17 18:04:06 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 17 May 2018 11:04:06 -0700
Subject: RFR: JDK-8202947: Fix minor issues with taglets
Message-ID: <5AFDC416.1060308@oracle.com>

Please review some changes to the doclet support for taglets.

The change was initially motivated by a desire to better understand 
which tags were supported in which contexts, to fix some issues in the 
doc comment specification [1].  That in turn led to some cleanup in the 
code to better understand the handling of such information in the code 
itself. Finally, after doing before/after checking on the Java SE API 
docs to verify that no change had occurred in the generated docs, a 
change -was- identified, fixing a previously unknown bug, which caused 
incorrect/inappropriate version info to appear in the generated docs for 
JDK 9 and 10.

The JBS issue for this work is [2], but any changes that would allow 
tags to appear in more places (implying a potential spec change) have 
been deferred for now.  In addition, as well as the previously unknown 
bug described above, another previously unknown bug has been identified, 
in the handling of the -tag option. This will be investigated 
separately, and additional tests provided.

In terms of this work, the primary file to review first is TagletManager 
[3].  While it is mostly cleanup, there is a new method to print out a 
dump of the taglet table, which can be activated by a new 
hidden/undocumented option. Secondarily, BaseTaglet [4] has been 
improved, to make it unnecessary for subtypes to override methods that 
define where the tag(let) can be used: the functionality is replaced by 
passing in a Set<Site> to the BaseTaglet constructor, where Site is a 
new enum whose members indicate the different places where a tag(let) 
may appear.

A minor change to SimpleTaglet allows a taglet to be disabled. This is 
used by the -author, -version, -nosince options, and by the 'X' 
character in the `locations` part of a `-tag` option.  Because this 
changes the way that @author and @version tags are handled, new tests 
are added for those tags, that exercise the tag and the corresponding 
option.

A new "golden file" test is added for the dump of the taglet table. This 
is partly to ensure the continued operation of the code to dump the 
taglet table, and partly to help detect any inadvertent changes to the 
taglet table.

-- Jon


[1] https://docs.oracle.com/javase/9/docs/specs/doc-comment-spec.html
[2] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/
[3] 
http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java.sdiff.html
[4] 
http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java.sdiff.html

From jonathan.gibbons at oracle.com  Fri May 18 22:51:45 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Fri, 18 May 2018 15:51:45 -0700 (PDT)
Subject: RFR: JDK-8196202: Javadoc should not generate frames by default
Message-ID: <5AFF5901.1040400@oracle.com>

Please review a small source change and corresponding test updates to 
javadoc,
so that the behavior is to not generate frames by default. (A future 
release will
remove support for frames altogether.)

Most test changes are tiny, and correspond to adding "--frames" to restore
the previous behavior. There should be a followup bug to change the test to
work without the --frames option.  The small test changes are best 
viewed through
Udiffs links. One test has non-trivial changes: TestFramesNoFramesTest.java.

The change is dependent on the CSR being approved.

JBS: https://bugs.openjdk.java.net/browse/JDK-8196202
CSR: https://bugs.openjdk.java.net/browse/JDK-8202961
Webrev: http://cr.openjdk.java.net/~jjg/8196202/webrev.00/

-- Jon

From jonathan.gibbons at oracle.com  Mon May 21 18:18:42 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 21 May 2018 11:18:42 -0700
Subject: RFR: JDK-8202947: Fix minor issues with taglets
In-Reply-To: <5AFDC416.1060308@oracle.com>
References: <5AFDC416.1060308@oracle.com>
Message-ID: <5B030D82.4070200@oracle.com>

webrev.01 contains a minor update to this review.

1. Dummy taglets are registered for @uses and @provides so that they 
appear in the printed taglet table
2. The test is updated for the @uses, @provides, and the JavaFX tags.

Webrev: http://cr.openjdk.java.net/~jjg/8202947/webrev.01/

-- Jon

On 05/17/2018 11:04 AM, Jonathan Gibbons wrote:
> Please review some changes to the doclet support for taglets.
>
> The change was initially motivated by a desire to better understand 
> which tags were supported in which contexts, to fix some issues in the 
> doc comment specification [1].  That in turn led to some cleanup in 
> the code to better understand the handling of such information in the 
> code itself. Finally, after doing before/after checking on the Java SE 
> API docs to verify that no change had occurred in the generated docs, 
> a change -was- identified, fixing a previously unknown bug, which 
> caused incorrect/inappropriate version info to appear in the generated 
> docs for JDK 9 and 10.
>
> The JBS issue for this work is [2], but any changes that would allow 
> tags to appear in more places (implying a potential spec change) have 
> been deferred for now.  In addition, as well as the previously unknown 
> bug described above, another previously unknown bug has been 
> identified, in the handling of the -tag option. This will be 
> investigated separately, and additional tests provided.
>
> In terms of this work, the primary file to review first is 
> TagletManager [3].  While it is mostly cleanup, there is a new method 
> to print out a dump of the taglet table, which can be activated by a 
> new hidden/undocumented option. Secondarily, BaseTaglet [4] has been 
> improved, to make it unnecessary for subtypes to override methods that 
> define where the tag(let) can be used: the functionality is replaced 
> by passing in a Set<Site> to the BaseTaglet constructor, where Site is 
> a new enum whose members indicate the different places where a 
> tag(let) may appear.
>
> A minor change to SimpleTaglet allows a taglet to be disabled. This is 
> used by the -author, -version, -nosince options, and by the 'X' 
> character in the `locations` part of a `-tag` option. Because this 
> changes the way that @author and @version tags are handled, new tests 
> are added for those tags, that exercise the tag and the corresponding 
> option.
>
> A new "golden file" test is added for the dump of the taglet table. 
> This is partly to ensure the continued operation of the code to dump 
> the taglet table, and partly to help detect any inadvertent changes to 
> the taglet table.
>
> -- Jon
>
>
> [1] https://docs.oracle.com/javase/9/docs/specs/doc-comment-spec.html
> [2] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/
> [3] 
> http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java.sdiff.html
> [4] 
> http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java.sdiff.html


From ksrinifmt at gmail.com  Tue May 22 17:20:58 2018
From: ksrinifmt at gmail.com (K S)
Date: Tue, 22 May 2018 10:20:58 -0700
Subject: RFR: JDK-8202947: Fix minor issues with taglets
In-Reply-To: <5B030D82.4070200@oracle.com>
References: <5AFDC416.1060308@oracle.com> <5B030D82.4070200@oracle.com>
Message-ID: <CAEXt0tTLyOgniZJnBWdSuFG=j06-TX+iQOY_rrsCix2zCdRH6A@mail.gmail.com>

Hi Jon,

The changes looks good, very nice cleanups.

Couple of minor comments and clarifications:

BaseConfiguration.java
I am assuming tokenize will not return a null.

+            switch (tokens.size()) {


SimpleTaglet.java

+                case 's':  case 'S':        // super-packages, anyone?

:)

+    private final LinkedHashMap<String,Taglet> allTaglets;

space after ,

 return b ? s : s.replaceAll(".", "."); // replace all with "."

I had to a double take the first argument is a regex, but the comment
helped.

Thanks

Kumar Srinivasan



On Mon, May 21, 2018 at 11:18 AM, Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> webrev.01 contains a minor update to this review.
>
> 1. Dummy taglets are registered for @uses and @provides so that they
> appear in the printed taglet table
> 2. The test is updated for the @uses, @provides, and the JavaFX tags.
>
> Webrev: http://cr.openjdk.java.net/~jjg/8202947/webrev.01/
>
> -- Jon
>
>
> On 05/17/2018 11:04 AM, Jonathan Gibbons wrote:
>
>> Please review some changes to the doclet support for taglets.
>>
>> The change was initially motivated by a desire to better understand which
>> tags were supported in which contexts, to fix some issues in the doc
>> comment specification [1].  That in turn led to some cleanup in the code to
>> better understand the handling of such information in the code itself.
>> Finally, after doing before/after checking on the Java SE API docs to
>> verify that no change had occurred in the generated docs, a change -was-
>> identified, fixing a previously unknown bug, which caused
>> incorrect/inappropriate version info to appear in the generated docs for
>> JDK 9 and 10.
>>
>> The JBS issue for this work is [2], but any changes that would allow tags
>> to appear in more places (implying a potential spec change) have been
>> deferred for now.  In addition, as well as the previously unknown bug
>> described above, another previously unknown bug has been identified, in the
>> handling of the -tag option. This will be investigated separately, and
>> additional tests provided.
>>
>> In terms of this work, the primary file to review first is TagletManager
>> [3].  While it is mostly cleanup, there is a new method to print out a dump
>> of the taglet table, which can be activated by a new hidden/undocumented
>> option. Secondarily, BaseTaglet [4] has been improved, to make it
>> unnecessary for subtypes to override methods that define where the tag(let)
>> can be used: the functionality is replaced by passing in a Set<Site> to the
>> BaseTaglet constructor, where Site is a new enum whose members indicate the
>> different places where a tag(let) may appear.
>>
>> A minor change to SimpleTaglet allows a taglet to be disabled. This is
>> used by the -author, -version, -nosince options, and by the 'X' character
>> in the `locations` part of a `-tag` option. Because this changes the way
>> that @author and @version tags are handled, new tests are added for those
>> tags, that exercise the tag and the corresponding option.
>>
>> A new "golden file" test is added for the dump of the taglet table. This
>> is partly to ensure the continued operation of the code to dump the taglet
>> table, and partly to help detect any inadvertent changes to the taglet
>> table.
>>
>> -- Jon
>>
>>
>> [1] https://docs.oracle.com/javase/9/docs/specs/doc-comment-spec.html
>> [2] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/
>> [3] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.ja
>> vadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/
>> taglets/TagletManager.java.sdiff.html
>> [4] http://cr.openjdk.java.net/~jjg/8202947/webrev.00/src/jdk.ja
>> vadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/
>> taglets/BaseTaglet.java.sdiff.html
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180522/642b9a16/attachment.html>

From rick.hillegas at gmail.com  Sun May 20 23:45:52 2018
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Sun, 20 May 2018 16:45:52 -0700
Subject: running javadoc against multiple modules
Message-ID: <60701f4d-b6b5-5ba3-7ac9-81d85d436a0b@gmail.com>

I hope that someone can point me at the right documentation for how to 
create javadoc on a multi-module project. My naive googling does not 
find any pertinent examples for how to do this from the command line via 
the javadoc tool. I have looked through the Java 9 tools documents 
titled "Javadoc Guide" and "Tools Reference" but I have not been able to 
puzzle out which combination of options will produce a single, unified 
set of javadoc for multiple modules. This is my first attempt to 
document a multi-module project, so, no doubt, I am missing something 
simple but crucial.

I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
tree looks like this:

./java
./java/firstmodule
./java/firstmodule/firstpackage
./java/firstmodule/firstpackage/FirstClass.java
./java/firstmodule/module-info.java
./java/secondmodule
./java/secondmodule/module-info.java
./java/secondmodule/secondpackage
./java/secondmodule/secondpackage/SecondClass.java


The module descriptors look like the following...

module org.test.firstmodule

{
  ?? requires java.base;
 ??? exports firstpackage;
}


...and...

module org.test.secondmodule

{
 ??? requires java.base;
 ??? requires org.test.firstmodule;
 ??? exports secondpackage;
}


I believe that I have written valid modules, because the following 
command does what I expect it to do:

 ? java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
 ?????? -m org.test.secondmodule/secondpackage.SecondClass


That is, the java command likes my modules well enough. But javadoc 
baffles me.

The following command...

 ? javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
 ???????? -d build/javadoc \
 ???????? firstpackage secondpackage


...runs without any errors or warnings. However, it produces odd results:

1) The top level index.html page lists only one module: 
org.test.firstmodule. I expected to see both modules on the landing page.

2) In addition, SecondClass.html reports that SecondClass lives in the 
org.test.firstmodule module. I expected that the class would report its 
home as org.test.secondmodule.

The following command...

 ? javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
 ????????? -d build/javadoc \
 ????????? firstpackage secondpackage


...raises the following error...

 ? javadoc: error - No source files for package firstpackage


And this command...

 ? javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
 ????????? --module org.test.firstmodule,org.test.secondmodule \
 ????????? -d build/javadoc \
 ????????? firstpackage secondpackage


...objects that...

 ? javadoc: error - module org.test.firstmodule not found.


Clearly, I've wandered off into the tall weeds. I would appreciate your 
advice and, if possible, a pointer to a primer on this topic.

Thanks,
-Rick


From sundararajan.athijegannathan at oracle.com  Thu May 24 08:08:46 2018
From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan)
Date: Thu, 24 May 2018 13:38:46 +0530
Subject: RFR 8203780: javadoc should be updated to use jquery 1.12.4 and jszip
 v3.1.5
Message-ID: <5B06730E.4070504@oracle.com>

Please review fix for https://bugs.openjdk.java.net/browse/JDK-8203780

http://cr.openjdk.java.net/~sundar/8203780/webrev.00/

Thanks,
-Sundar

From sundararajan.athijegannathan at oracle.com  Thu May 24 15:12:39 2018
From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan)
Date: Thu, 24 May 2018 20:42:39 +0530
Subject: RFR 8203780: javadoc should be updated to use jquery 1.12.4 and
 jszip v3.1.5
In-Reply-To: <5B06730E.4070504@oracle.com>
References: <5B06730E.4070504@oracle.com>
Message-ID: <5B06D667.4070409@oracle.com>

Please ignore this RFR. I need to update jquery-ui.js as well. I'll send 
a new RFR and update bug description as well.

Thanks,
-Sundar

On 24/05/18, 1:38 PM, Sundararajan Athijegannathan wrote:
> Please review fix for https://bugs.openjdk.java.net/browse/JDK-8203780
>
> http://cr.openjdk.java.net/~sundar/8203780/webrev.00/
>
> Thanks,
> -Sundar

From ksrinifmt at gmail.com  Thu May 24 16:15:53 2018
From: ksrinifmt at gmail.com (K S)
Date: Thu, 24 May 2018 09:15:53 -0700
Subject: RFR: JDK-8196202: Javadoc should not generate frames by default
In-Reply-To: <5AFF5901.1040400@oracle.com>
References: <5AFF5901.1040400@oracle.com>
Message-ID: <CAEXt0tQmE_erni_ajSeZR8cN3iu8PyXyzJJdAd-nE+vQMXEHVQ@mail.gmail.com>

Hi Jon,

Looks ok to me.

Thanks
Kumar Srinivasan


On Fri, May 18, 2018 at 3:51 PM, Jonathan Gibbons <
jonathan.gibbons at oracle.com> wrote:

> Please review a small source change and corresponding test updates to
> javadoc,
> so that the behavior is to not generate frames by default. (A future
> release will
> remove support for frames altogether.)
>
> Most test changes are tiny, and correspond to adding "--frames" to restore
> the previous behavior. There should be a followup bug to change the test to
> work without the --frames option.  The small test changes are best viewed
> through
> Udiffs links. One test has non-trivial changes:
> TestFramesNoFramesTest.java.
>
> The change is dependent on the CSR being approved.
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8196202
> CSR: https://bugs.openjdk.java.net/browse/JDK-8202961
> Webrev: http://cr.openjdk.java.net/~jjg/8196202/webrev.00/
>
> -- Jon
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180524/bc9477c3/attachment.html>

From priya.lakshmi.muthuswamy at oracle.com  Mon May 28 11:05:51 2018
From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy)
Date: Mon, 28 May 2018 16:35:51 +0530
Subject: RFR:JDK-8202627:javadoc generates broken links to deprecated items
 when -nodeprecated is used
Message-ID: <277f93de-53a7-5ebd-765a-7ce4812c9b45@oracle.com>

Hi,

Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8202627
webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202627/webrev.00/

Thanks,
Priya

From jonathan.gibbons at oracle.com  Tue May 29 18:33:10 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 29 May 2018 11:33:10 -0700
Subject: running javadoc against multiple modules
In-Reply-To: <60701f4d-b6b5-5ba3-7ac9-81d85d436a0b@gmail.com>
References: <60701f4d-b6b5-5ba3-7ac9-81d85d436a0b@gmail.com>
Message-ID: <5B0D9CE6.2090308@oracle.com>

Rick,

Set --module-sourcepath to the directory containing the modules.

Something like this should work for you:

     javadoc  --module-source-path ./java -d build/javadoc --module 
firstmodule,secondmodule

-- Jon

On 05/20/2018 04:45 PM, Rick Hillegas wrote:
> I hope that someone can point me at the right documentation for how to 
> create javadoc on a multi-module project. My naive googling does not 
> find any pertinent examples for how to do this from the command line 
> via the javadoc tool. I have looked through the Java 9 tools documents 
> titled "Javadoc Guide" and "Tools Reference" but I have not been able 
> to puzzle out which combination of options will produce a single, 
> unified set of javadoc for multiple modules. This is my first attempt 
> to document a multi-module project, so, no doubt, I am missing 
> something simple but crucial.
>
> I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
> tree looks like this:
>
> ./java
> ./java/firstmodule
> ./java/firstmodule/firstpackage
> ./java/firstmodule/firstpackage/FirstClass.java
> ./java/firstmodule/module-info.java
> ./java/secondmodule
> ./java/secondmodule/module-info.java
> ./java/secondmodule/secondpackage
> ./java/secondmodule/secondpackage/SecondClass.java
>
>
> The module descriptors look like the following...
>
> module org.test.firstmodule
>
> {
>     requires java.base;
>     exports firstpackage;
> }
>
>
> ...and...
>
> module org.test.secondmodule
>
> {
>     requires java.base;
>     requires org.test.firstmodule;
>     exports secondpackage;
> }
>
>
> I believe that I have written valid modules, because the following 
> command does what I expect it to do:
>
>   java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
>        -m org.test.secondmodule/secondpackage.SecondClass
>
>
> That is, the java command likes my modules well enough. But javadoc 
> baffles me.
>
> The following command...
>
>   javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
>          -d build/javadoc \
>          firstpackage secondpackage
>
>
> ...runs without any errors or warnings. However, it produces odd results:
>
> 1) The top level index.html page lists only one module: 
> org.test.firstmodule. I expected to see both modules on the landing page.
>
> 2) In addition, SecondClass.html reports that SecondClass lives in the 
> org.test.firstmodule module. I expected that the class would report 
> its home as org.test.secondmodule.
>
> The following command...
>
>   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>           -d build/javadoc \
>           firstpackage secondpackage
>
>
> ...raises the following error...
>
>   javadoc: error - No source files for package firstpackage
>
>
> And this command...
>
>   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>           --module org.test.firstmodule,org.test.secondmodule \
>           -d build/javadoc \
>           firstpackage secondpackage
>
>
> ...objects that...
>
>   javadoc: error - module org.test.firstmodule not found.
>
>
> Clearly, I've wandered off into the tall weeds. I would appreciate 
> your advice and, if possible, a pointer to a primer on this topic.
>
> Thanks,
> -Rick
>


From jonathan.gibbons at oracle.com  Tue May 29 20:45:38 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 29 May 2018 13:45:38 -0700
Subject: RFR: JDK-8202959: Rearrange the top and bottom navigation bar in
 the javadoc generated pages
Message-ID: <5B0DBBF2.4040805@oracle.com>

Please review this change to simplify the navigation bar found at the 
top and bottom of most pages.

In the lower part of the navigation bar, the "ALL_CLASSES" link is 
removed, and the remaining items are composed in a single line.

The link for for the list of all classes, and another for the list of 
all packages, are now available on the "index" page, found by clicking 
on the INDEX link in the upper part of the navigation bar.

JBS: https://bugs.openjdk.java.net/browse/JDK-8202959
Webrev: http://cr.openjdk.java.net/~jjg/8187794/webrev.00/index.html

-- Jon

From rick.hillegas at gmail.com  Tue May 29 23:02:20 2018
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Tue, 29 May 2018 16:02:20 -0700
Subject: Fwd: Re: running javadoc against multiple modules
In-Reply-To: <5B0D9CE6.2090308@oracle.com>
References: <5B0D9CE6.2090308@oracle.com>
Message-ID: <aa82b5d6-2f66-c10e-ba30-f91f391e6b9a@gmail.com>

Thanks, Jon. That moved the problem forward. Now I am getting an error 
because a module's name does not match the root directory of its source 
code. The following command...

 ? javadoc --module-source-path ./java \

 ???? -d build/javadoc \

 ???? --module firstmodule,secondmodule


...raises the following errors:

 ? ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule
    does not match expected name secondmodule

 ? module org.test.secondmodule

 ? ^

 ? ./java/secondmodule/module-info.java:5: error: module not found:
     org.test.firstmodule

 ??? requires org.test.firstmodule;

 ???????????????????? ^

 ? error: cannot access module-info

 ??? cannot resolve modules

 ? 3 errors


I get a different error when I change the names of the modules which I 
hand to the --module switch. The following command...

 ? javadoc --module-source-path ./java \

 ??? -d build/javadoc \

 ??? --module org.test.firstmodule,org.test.secondmodule


...raises the following error...

 ? javadoc: error - module org.test.firstmodule not found.


I have attached a tarball of my project.

Thanks for any advice you can give me,
-Rick



-------- Forwarded Message --------
Subject: 	Re: running javadoc against multiple modules
Date: 	Tue, 29 May 2018 11:33:10 -0700
From: 	Jonathan Gibbons <jonathan.gibbons at oracle.com>
To: 	javadoc-dev at openjdk.java.net



Rick,

Set --module-sourcepath to the directory containing the modules.

Something like this should work for you:

     javadoc  --module-source-path ./java -d build/javadoc --module
firstmodule,secondmodule

-- Jon

On 05/20/2018 04:45 PM, Rick Hillegas wrote:
> I hope that someone can point me at the right documentation for how to 
> create javadoc on a multi-module project. My naive googling does not 
> find any pertinent examples for how to do this from the command line 
> via the javadoc tool. I have looked through the Java 9 tools documents 
> titled "Javadoc Guide" and "Tools Reference" but I have not been able 
> to puzzle out which combination of options will produce a single, 
> unified set of javadoc for multiple modules. This is my first attempt 
> to document a multi-module project, so, no doubt, I am missing 
> something simple but crucial.
>
> I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
> tree looks like this:
>
> ./java
> ./java/firstmodule
> ./java/firstmodule/firstpackage
> ./java/firstmodule/firstpackage/FirstClass.java
> ./java/firstmodule/module-info.java
> ./java/secondmodule
> ./java/secondmodule/module-info.java
> ./java/secondmodule/secondpackage
> ./java/secondmodule/secondpackage/SecondClass.java
>
>
> The module descriptors look like the following...
>
> module org.test.firstmodule
>
> {
>     requires java.base;
>     exports firstpackage;
> }
>
>
> ...and...
>
> module org.test.secondmodule
>
> {
>     requires java.base;
>     requires org.test.firstmodule;
>     exports secondpackage;
> }
>
>
> I believe that I have written valid modules, because the following 
> command does what I expect it to do:
>
>   java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
>        -m org.test.secondmodule/secondpackage.SecondClass
>
>
> That is, the java command likes my modules well enough. But javadoc 
> baffles me.
>
> The following command...
>
>   javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
>          -d build/javadoc \
>          firstpackage secondpackage
>
>
> ...runs without any errors or warnings. However, it produces odd results:
>
> 1) The top level index.html page lists only one module: 
> org.test.firstmodule. I expected to see both modules on the landing page.
>
> 2) In addition, SecondClass.html reports that SecondClass lives in the 
> org.test.firstmodule module. I expected that the class would report 
> its home as org.test.secondmodule.
>
> The following command...
>
>   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>           -d build/javadoc \
>           firstpackage secondpackage
>
>
> ...raises the following error...
>
>   javadoc: error - No source files for package firstpackage
>
>
> And this command...
>
>   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>           --module org.test.firstmodule,org.test.secondmodule \
>           -d build/javadoc \
>           firstpackage secondpackage
>
>
> ...objects that...
>
>   javadoc: error - module org.test.firstmodule not found.
>
>
> Clearly, I've wandered off into the tall weeds. I would appreciate 
> your advice and, if possible, a pointer to a primer on this topic.
>
> Thanks,
> -Rick
>


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180529/bda83f88/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: zdoc.tar
Type: application/x-tar
Size: 11264 bytes
Desc: not available
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180529/bda83f88/zdoc-0001.tar>

From ksrinifmt at gmail.com  Wed May 30 14:28:40 2018
From: ksrinifmt at gmail.com (Kumar Srinivasan)
Date: Wed, 30 May 2018 07:28:40 -0700
Subject: RFR:JDK-8202627:javadoc generates broken links to deprecated
 items when -nodeprecated is used
In-Reply-To: <277f93de-53a7-5ebd-765a-7ce4812c9b45@oracle.com>
References: <277f93de-53a7-5ebd-765a-7ce4812c9b45@oracle.com>
Message-ID: <CAEXt0tTFt-pxuZp4Ma9rY9vZLW177WyGanM-RMDG9d4WduPPgw@mail.gmail.com>

Hello Priya,

The specific changes looks ok to me.

As a separate effort, I recommend searching for other accesses in the Doclet
to javax.lang.model through calls in Utils, these need to be investigated.

Note: there maybe legitimate cases where raw members and types are needed,
but for the most part the Doclet should use VMT for all these purposes. I
removed
some of these while doing the VMT work (Index generators), but there maybe
more,
in any case this effort needs to be done cautiously with a before/after
comparison.

Kumar


On Mon, May 28, 2018 at 4:05 AM, Priya Lakshmi Muthuswamy <
priya.lakshmi.muthuswamy at oracle.com> wrote:

> Hi,
>
> Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8202627
> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202627/webrev.00/
>
> Thanks,
> Priya
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180530/628d73f1/attachment.html>

From jonathan.gibbons at oracle.com  Wed May 30 14:34:20 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 30 May 2018 07:34:20 -0700
Subject: Fwd: Re: running javadoc against multiple modules
In-Reply-To: <aa82b5d6-2f66-c10e-ba30-f91f391e6b9a@gmail.com>
References: <5B0D9CE6.2090308@oracle.com>
 <aa82b5d6-2f66-c10e-ba30-f91f391e6b9a@gmail.com>
Message-ID: <da75c169-a593-8809-2c18-db5cc21975f8@oracle.com>

Sorry, I missed that detail when looking at your example yesterday.

The error message says it all.

When you're working with multiple modules on the module source path, 
each module must be in a directory that is named after the module it 
contains. Think of it as the module-level equivalent of the requirement 
that classes in a package hierarchy should be organized in a directory 
hierarchy that mirrors the package hierarchy.

If your modules are named org.test.firstmodule and 
org.test.secondmodule, your ./java directory should contain direct 
subdirectories with those exact names.? Within each directory, you can 
place the package hierarchy for the content of that module. In simple 
cases, you can place the package hierarchy directly in the module 
directory, although with a more complex value for the 
--module-source-path option, you can set up a system with intervening 
directories between the module directory and the root of the package 
hierarchy.

The module paths are described in JEP 261. 
http://openjdk.java.net/jeps/261? Although that JEP does not call out 
javadoc, the description for javac essentially applies to javadoc as well.

-- Jon


On 5/29/18 4:02 PM, Rick Hillegas wrote:
>
> Thanks, Jon. That moved the problem forward. Now I am getting an error 
> because a module's name does not match the root directory of its 
> source code. The following command...
>
>  ? javadoc --module-source-path ./java \
>  ???? -d build/javadoc \
>  ???? --module firstmodule,secondmodule
>
>
> ...raises the following errors:
>
>  ? ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule
>     does not match expected name secondmodule
>  ? module org.test.secondmodule
>  ? ^
>  ? ./java/secondmodule/module-info.java:5: error: module not found:
>      org.test.firstmodule
>  ??? requires org.test.firstmodule;
>  ???????????????????? ^
>  ? error: cannot access module-info
>  ??? cannot resolve modules
>  ? 3 errors
>
>
> I get a different error when I change the names of the modules which I 
> hand to the --module switch. The following command...
>
>  ? javadoc --module-source-path ./java \
>  ??? -d build/javadoc \
>  ??? --module org.test.firstmodule,org.test.secondmodule
>
>
> ...raises the following error...
>
>  ? javadoc: error - module org.test.firstmodule not found.
>
>
> I have attached a tarball of my project.
>
> Thanks for any advice you can give me,
> -Rick
>
>
>
> -------- Forwarded Message --------
> Subject: 	Re: running javadoc against multiple modules
> Date: 	Tue, 29 May 2018 11:33:10 -0700
> From: 	Jonathan Gibbons <jonathan.gibbons at oracle.com>
> To: 	javadoc-dev at openjdk.java.net
>
>
>
> Rick,
>
> Set --module-sourcepath to the directory containing the modules.
>
> Something like this should work for you:
>
>      javadoc  --module-source-path ./java -d build/javadoc --module
> firstmodule,secondmodule
>
> -- Jon
>
> On 05/20/2018 04:45 PM, Rick Hillegas wrote:
> > I hope that someone can point me at the right documentation for how to 
> > create javadoc on a multi-module project. My naive googling does not 
> > find any pertinent examples for how to do this from the command line 
> > via the javadoc tool. I have looked through the Java 9 tools documents 
> > titled "Javadoc Guide" and "Tools Reference" but I have not been able 
> > to puzzle out which combination of options will produce a single, 
> > unified set of javadoc for multiple modules. This is my first attempt 
> > to document a multi-module project, so, no doubt, I am missing 
> > something simple but crucial.
> >
> > I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
> > tree looks like this:
> >
> > ./java
> > ./java/firstmodule
> > ./java/firstmodule/firstpackage
> > ./java/firstmodule/firstpackage/FirstClass.java
> > ./java/firstmodule/module-info.java
> > ./java/secondmodule
> > ./java/secondmodule/module-info.java
> > ./java/secondmodule/secondpackage
> > ./java/secondmodule/secondpackage/SecondClass.java
> >
> >
> > The module descriptors look like the following...
> >
> > module org.test.firstmodule
> >
> > {
> >     requires java.base;
> >     exports firstpackage;
> > }
> >
> >
> > ...and...
> >
> > module org.test.secondmodule
> >
> > {
> >     requires java.base;
> >     requires org.test.firstmodule;
> >     exports secondpackage;
> > }
> >
> >
> > I believe that I have written valid modules, because the following 
> > command does what I expect it to do:
> >
> >   java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
> >        -m org.test.secondmodule/secondpackage.SecondClass
> >
> >
> > That is, the java command likes my modules well enough. But javadoc 
> > baffles me.
> >
> > The following command...
> >
> >   javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
> >          -d build/javadoc \
> >          firstpackage secondpackage
> >
> >
> > ...runs without any errors or warnings. However, it produces odd results:
> >
> > 1) The top level index.html page lists only one module: 
> > org.test.firstmodule. I expected to see both modules on the landing page.
> >
> > 2) In addition, SecondClass.html reports that SecondClass lives in the 
> > org.test.firstmodule module. I expected that the class would report 
> > its home as org.test.secondmodule.
> >
> > The following command...
> >
> >   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
> >           -d build/javadoc \
> >           firstpackage secondpackage
> >
> >
> > ...raises the following error...
> >
> >   javadoc: error - No source files for package firstpackage
> >
> >
> > And this command...
> >
> >   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
> >           --module org.test.firstmodule,org.test.secondmodule \
> >           -d build/javadoc \
> >           firstpackage secondpackage
> >
> >
> > ...objects that...
> >
> >   javadoc: error - module org.test.firstmodule not found.
> >
> >
> > Clearly, I've wandered off into the tall weeds. I would appreciate 
> > your advice and, if possible, a pointer to a primer on this topic.
> >
> > Thanks,
> > -Rick
> >
>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180530/ef8bfffc/attachment.html>

From jonathan.gibbons at oracle.com  Wed May 30 23:36:42 2018
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 30 May 2018 16:36:42 -0700
Subject: Fwd: Re: running javadoc against multiple modules
In-Reply-To: <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com>
References: <5B0D9CE6.2090308@oracle.com>
 <aa82b5d6-2f66-c10e-ba30-f91f391e6b9a@gmail.com>
 <da75c169-a593-8809-2c18-db5cc21975f8@oracle.com>
 <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com>
Message-ID: <aeaaa57e-a4cc-d8d8-cccd-040c282ef221@oracle.com>

Rick,

Thank you for explaining the context of your questions.

With respect, you are mistaken with respect to javac's behavior, if only 
because it's the same code shared by javac and javadoc,

--module-source-path requires there to be a level in the directory 
hierarchy that is named for the module.? The name is required in order 
to find the source for a module, when resolve a directive like "requires 
moduleName;".? Just as javac requires that classes can be looked up in a 
directory hierarchy that corresponds to the package hierarchy, so too 
does javac and javadoc impose a requirement that the source for a module 
be in a suitably-named directory when using the module source path.

It may be that you have not encountered the equivalent situation in 
javac if you have managed to compile your code one module at a time, 
placing the output from previous compilations on the module path. In 
that situation, would would not need to use the --module-source-path 
option, which is necessary when you want to read/analyze/compile the 
source code for several modules at once.

Although I grant that the text in JEP 261 could be clearer, this is the 
relevant text:
>
> In large systems the source code for a particular module may be spread 
> across several different directories.In the JDK itself 
> <http://openjdk.java.net/jeps/201>,/e.g./, the source files for a 
> module may be found in any one of the 
> directories|src/<module>/share/classes|,|src/<module>/<os>/classes|, 
> or|build/gensrc/<module>|, where|<os>|is the name of the target 
> operating system. To express this in a module source path while 
> preserving module identities we allow each element of such a path to 
> use braces (|{|and|}|) to enclose commas-separated lists of 
> alternatives and a single asterisk (|*|) to stand for the module name. 
> The module source path for the JDK can then be written as
>
> |{src/*/{share,<os>}/classes,build/gensrc/*}|

The reference to '*' is the presence of the module name.

I understand the difficulty this restriction may cause some existing 
older software systems. At some level, I'm impressed you have gotten as 
far as you have without running into this restriction before!

All that having been said, there may be a way forward for you.? The 
following may seen a bit cumbersome, but it may allow you to run javadoc 
(or javac) without renaming your source directories.? You can do this 
with a combination of --module-source-path and --patch-module, as follows:

1. Point --module-source-path at an empty directory.? The presence of 
the option is required so that the tool is put into "multi-module mode".

2. For each of the modules you want to process, use an option like this:
 ??? ??? --patch-module <module-name>=<path-for-module-source>

 ??? The <module-name> is as it would appear in the module declaration;? 
the <path-for-module-source> is a "source path", meaning one or more 
directories separated by the system path separator character (either ':' 
on Unix-like systems, or ';' on Windows.)? As a source path, the 
directories on the path must all be directories at the root of a package 
hierarchy.

 ??? So, for example, for one of your modules, the option would be

 ??? ??? --patch-module org.test.firstmodule=./java/firstmodule

 ??? And you would repeat that as needed for all the other modules you 
want to pass to javadoc

-- Jon


On 5/30/18 4:08 PM, Rick Hillegas wrote:
> Thanks for that explanation, Jon.
>
> I'm asking these questions because I'm near the end of modularizing a 
> very old body of software, Apache Derby. I have successfully created 
> module descriptors for all of the Derby components and I have not had 
> to rename any directories. The naming limitation you describe does not 
> constrain javac. Javac does not impose any restrictions on the names 
> of the root directories of components.
>
> I do not see this limitation in JEP 261. Stephen Colbourne seems to 
> recommend the practice which you are advocating 
> (http://blog.joda.org/2017/04/java-se-9-jpms-module-naming.html) but 
> he merely states a strong recommendation. My sense is that it is a 
> best practice for greenfield projects. It is clearly a big hurdle for 
> legacy projects to surmount.
>
> Thanks for this clarification,
> -Rick
>
> On 5/30/18 7:34 AM, Jonathan Gibbons wrote:
>>
>> Sorry, I missed that detail when looking at your example yesterday.
>>
>> The error message says it all.
>>
>> When you're working with multiple modules on the module source path, 
>> each module must be in a directory that is named after the module it 
>> contains. Think of it as the module-level equivalent of the 
>> requirement that classes in a package hierarchy should be organized 
>> in a directory hierarchy that mirrors the package hierarchy.
>>
>> If your modules are named org.test.firstmodule and 
>> org.test.secondmodule, your ./java directory should contain direct 
>> subdirectories with those exact names.? Within each directory, you 
>> can place the package hierarchy for the content of that module.? In 
>> simple cases, you can place the package hierarchy directly in the 
>> module directory, although with a more complex value for the 
>> --module-source-path option, you can set up a system with intervening 
>> directories between the module directory and the root of the package 
>> hierarchy.
>>
>> The module paths are described in JEP 261. 
>> http://openjdk.java.net/jeps/261 Although that JEP does not call out 
>> javadoc, the description for javac essentially applies to javadoc as 
>> well.
>>
>> -- Jon
>>
>>
>> On 5/29/18 4:02 PM, Rick Hillegas wrote:
>>>
>>> Thanks, Jon. That moved the problem forward. Now I am getting an 
>>> error because a module's name does not match the root directory of 
>>> its source code. The following command...
>>>
>>>  ? javadoc --module-source-path ./java \
>>>  ???? -d build/javadoc \
>>>  ???? --module firstmodule,secondmodule
>>>
>>>
>>> ...raises the following errors:
>>>
>>>  ? ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule
>>>     does not match expected name secondmodule
>>>  ? module org.test.secondmodule
>>>  ? ^
>>>  ? ./java/secondmodule/module-info.java:5: error: module not found:
>>>      org.test.firstmodule
>>>  ??? requires org.test.firstmodule;
>>>  ???????????????????? ^
>>>  ? error: cannot access module-info
>>>  ??? cannot resolve modules
>>>  ? 3 errors
>>>
>>>
>>> I get a different error when I change the names of the modules which 
>>> I hand to the --module switch. The following command...
>>>
>>>  ? javadoc --module-source-path ./java \
>>>  ??? -d build/javadoc \
>>>  ??? --module org.test.firstmodule,org.test.secondmodule
>>>
>>>
>>> ...raises the following error...
>>>
>>>  ? javadoc: error - module org.test.firstmodule not found.
>>>
>>>
>>> I have attached a tarball of my project.
>>>
>>> Thanks for any advice you can give me,
>>> -Rick
>>>
>>>
>>>
>>> -------- Forwarded Message --------
>>> Subject: 	Re: running javadoc against multiple modules
>>> Date: 	Tue, 29 May 2018 11:33:10 -0700
>>> From: 	Jonathan Gibbons <jonathan.gibbons at oracle.com>
>>> To: 	javadoc-dev at openjdk.java.net
>>>
>>>
>>>
>>> Rick,
>>>
>>> Set --module-sourcepath to the directory containing the modules.
>>>
>>> Something like this should work for you:
>>>
>>>      javadoc  --module-source-path ./java -d build/javadoc --module
>>> firstmodule,secondmodule
>>>
>>> -- Jon
>>>
>>> On 05/20/2018 04:45 PM, Rick Hillegas wrote:
>>> > I hope that someone can point me at the right documentation for how to 
>>> > create javadoc on a multi-module project. My naive googling does not 
>>> > find any pertinent examples for how to do this from the command line 
>>> > via the javadoc tool. I have looked through the Java 9 tools documents 
>>> > titled "Javadoc Guide" and "Tools Reference" but I have not been able 
>>> > to puzzle out which combination of options will produce a single, 
>>> > unified set of javadoc for multiple modules. This is my first attempt 
>>> > to document a multi-module project, so, no doubt, I am missing 
>>> > something simple but crucial.
>>> >
>>> > I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
>>> > tree looks like this:
>>> >
>>> > ./java
>>> > ./java/firstmodule
>>> > ./java/firstmodule/firstpackage
>>> > ./java/firstmodule/firstpackage/FirstClass.java
>>> > ./java/firstmodule/module-info.java
>>> > ./java/secondmodule
>>> > ./java/secondmodule/module-info.java
>>> > ./java/secondmodule/secondpackage
>>> > ./java/secondmodule/secondpackage/SecondClass.java
>>> >
>>> >
>>> > The module descriptors look like the following...
>>> >
>>> > module org.test.firstmodule
>>> >
>>> > {
>>> >     requires java.base;
>>> >     exports firstpackage;
>>> > }
>>> >
>>> >
>>> > ...and...
>>> >
>>> > module org.test.secondmodule
>>> >
>>> > {
>>> >     requires java.base;
>>> >     requires org.test.firstmodule;
>>> >     exports secondpackage;
>>> > }
>>> >
>>> >
>>> > I believe that I have written valid modules, because the following 
>>> > command does what I expect it to do:
>>> >
>>> >   java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
>>> >        -m org.test.secondmodule/secondpackage.SecondClass
>>> >
>>> >
>>> > That is, the java command likes my modules well enough. But javadoc 
>>> > baffles me.
>>> >
>>> > The following command...
>>> >
>>> >   javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
>>> >          -d build/javadoc \
>>> >          firstpackage secondpackage
>>> >
>>> >
>>> > ...runs without any errors or warnings. However, it produces odd results:
>>> >
>>> > 1) The top level index.html page lists only one module: 
>>> > org.test.firstmodule. I expected to see both modules on the landing page.
>>> >
>>> > 2) In addition, SecondClass.html reports that SecondClass lives in the 
>>> > org.test.firstmodule module. I expected that the class would report 
>>> > its home as org.test.secondmodule.
>>> >
>>> > The following command...
>>> >
>>> >   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>>> >           -d build/javadoc \
>>> >           firstpackage secondpackage
>>> >
>>> >
>>> > ...raises the following error...
>>> >
>>> >   javadoc: error - No source files for package firstpackage
>>> >
>>> >
>>> > And this command...
>>> >
>>> >   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>>> >           --module org.test.firstmodule,org.test.secondmodule \
>>> >           -d build/javadoc \
>>> >           firstpackage secondpackage
>>> >
>>> >
>>> > ...objects that...
>>> >
>>> >   javadoc: error - module org.test.firstmodule not found.
>>> >
>>> >
>>> > Clearly, I've wandered off into the tall weeds. I would appreciate 
>>> > your advice and, if possible, a pointer to a primer on this topic.
>>> >
>>> > Thanks,
>>> > -Rick
>>> >
>>>
>>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180530/9598bb2d/attachment-0001.html>

From rick.hillegas at gmail.com  Wed May 30 23:08:09 2018
From: rick.hillegas at gmail.com (Rick Hillegas)
Date: Wed, 30 May 2018 16:08:09 -0700
Subject: Fwd: Re: running javadoc against multiple modules
In-Reply-To: <da75c169-a593-8809-2c18-db5cc21975f8@oracle.com>
References: <5B0D9CE6.2090308@oracle.com>
 <aa82b5d6-2f66-c10e-ba30-f91f391e6b9a@gmail.com>
 <da75c169-a593-8809-2c18-db5cc21975f8@oracle.com>
Message-ID: <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com>

Thanks for that explanation, Jon.

I'm asking these questions because I'm near the end of modularizing a 
very old body of software, Apache Derby. I have successfully created 
module descriptors for all of the Derby components and I have not had to 
rename any directories. The naming limitation you describe does not 
constrain javac. Javac does not impose any restrictions on the names of 
the root directories of components.

I do not see this limitation in JEP 261. Stephen Colbourne seems to 
recommend the practice which you are advocating 
(http://blog.joda.org/2017/04/java-se-9-jpms-module-naming.html) but he 
merely states a strong recommendation. My sense is that it is a best 
practice for greenfield projects. It is clearly a big hurdle for legacy 
projects to surmount.

Thanks for this clarification,
-Rick

On 5/30/18 7:34 AM, Jonathan Gibbons wrote:
>
> Sorry, I missed that detail when looking at your example yesterday.
>
> The error message says it all.
>
> When you're working with multiple modules on the module source path, 
> each module must be in a directory that is named after the module it 
> contains. Think of it as the module-level equivalent of the 
> requirement that classes in a package hierarchy should be organized in 
> a directory hierarchy that mirrors the package hierarchy.
>
> If your modules are named org.test.firstmodule and 
> org.test.secondmodule, your ./java directory should contain direct 
> subdirectories with those exact names.? Within each directory, you can 
> place the package hierarchy for the content of that module.? In simple 
> cases, you can place the package hierarchy directly in the module 
> directory, although with a more complex value for the 
> --module-source-path option, you can set up a system with intervening 
> directories between the module directory and the root of the package 
> hierarchy.
>
> The module paths are described in JEP 261. 
> http://openjdk.java.net/jeps/261 Although that JEP does not call out 
> javadoc, the description for javac essentially applies to javadoc as well.
>
> -- Jon
>
>
> On 5/29/18 4:02 PM, Rick Hillegas wrote:
>>
>> Thanks, Jon. That moved the problem forward. Now I am getting an 
>> error because a module's name does not match the root directory of 
>> its source code. The following command...
>>
>>  ? javadoc --module-source-path ./java \
>>  ???? -d build/javadoc \
>>  ???? --module firstmodule,secondmodule
>>
>>
>> ...raises the following errors:
>>
>>  ? ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule
>>     does not match expected name secondmodule
>>  ? module org.test.secondmodule
>>  ? ^
>>  ? ./java/secondmodule/module-info.java:5: error: module not found:
>>      org.test.firstmodule
>>  ??? requires org.test.firstmodule;
>>  ???????????????????? ^
>>  ? error: cannot access module-info
>>  ??? cannot resolve modules
>>  ? 3 errors
>>
>>
>> I get a different error when I change the names of the modules which 
>> I hand to the --module switch. The following command...
>>
>>  ? javadoc --module-source-path ./java \
>>  ??? -d build/javadoc \
>>  ??? --module org.test.firstmodule,org.test.secondmodule
>>
>>
>> ...raises the following error...
>>
>>  ? javadoc: error - module org.test.firstmodule not found.
>>
>>
>> I have attached a tarball of my project.
>>
>> Thanks for any advice you can give me,
>> -Rick
>>
>>
>>
>> -------- Forwarded Message --------
>> Subject: 	Re: running javadoc against multiple modules
>> Date: 	Tue, 29 May 2018 11:33:10 -0700
>> From: 	Jonathan Gibbons <jonathan.gibbons at oracle.com>
>> To: 	javadoc-dev at openjdk.java.net
>>
>>
>>
>> Rick,
>>
>> Set --module-sourcepath to the directory containing the modules.
>>
>> Something like this should work for you:
>>
>>      javadoc  --module-source-path ./java -d build/javadoc --module
>> firstmodule,secondmodule
>>
>> -- Jon
>>
>> On 05/20/2018 04:45 PM, Rick Hillegas wrote:
>> > I hope that someone can point me at the right documentation for how to 
>> > create javadoc on a multi-module project. My naive googling does not 
>> > find any pertinent examples for how to do this from the command line 
>> > via the javadoc tool. I have looked through the Java 9 tools documents 
>> > titled "Javadoc Guide" and "Tools Reference" but I have not been able 
>> > to puzzle out which combination of options will produce a single, 
>> > unified set of javadoc for multiple modules. This is my first attempt 
>> > to document a multi-module project, so, no doubt, I am missing 
>> > something simple but crucial.
>> >
>> > I am using "Java(TM) SE Runtime Environment (build 9+181)". My source 
>> > tree looks like this:
>> >
>> > ./java
>> > ./java/firstmodule
>> > ./java/firstmodule/firstpackage
>> > ./java/firstmodule/firstpackage/FirstClass.java
>> > ./java/firstmodule/module-info.java
>> > ./java/secondmodule
>> > ./java/secondmodule/module-info.java
>> > ./java/secondmodule/secondpackage
>> > ./java/secondmodule/secondpackage/SecondClass.java
>> >
>> >
>> > The module descriptors look like the following...
>> >
>> > module org.test.firstmodule
>> >
>> > {
>> >     requires java.base;
>> >     exports firstpackage;
>> > }
>> >
>> >
>> > ...and...
>> >
>> > module org.test.secondmodule
>> >
>> > {
>> >     requires java.base;
>> >     requires org.test.firstmodule;
>> >     exports secondpackage;
>> > }
>> >
>> >
>> > I believe that I have written valid modules, because the following 
>> > command does what I expect it to do:
>> >
>> >   java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \
>> >        -m org.test.secondmodule/secondpackage.SecondClass
>> >
>> >
>> > That is, the java command likes my modules well enough. But javadoc 
>> > baffles me.
>> >
>> > The following command...
>> >
>> >   javadoc -sourcepath ./java/firstmodule:./java/secondmodule \
>> >          -d build/javadoc \
>> >          firstpackage secondpackage
>> >
>> >
>> > ...runs without any errors or warnings. However, it produces odd results:
>> >
>> > 1) The top level index.html page lists only one module: 
>> > org.test.firstmodule. I expected to see both modules on the landing page.
>> >
>> > 2) In addition, SecondClass.html reports that SecondClass lives in the 
>> > org.test.firstmodule module. I expected that the class would report 
>> > its home as org.test.secondmodule.
>> >
>> > The following command...
>> >
>> >   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>> >           -d build/javadoc \
>> >           firstpackage secondpackage
>> >
>> >
>> > ...raises the following error...
>> >
>> >   javadoc: error - No source files for package firstpackage
>> >
>> >
>> > And this command...
>> >
>> >   javadoc --module-source-path ./java/firstmodule:./java/secondmodule \
>> >           --module org.test.firstmodule,org.test.secondmodule \
>> >           -d build/javadoc \
>> >           firstpackage secondpackage
>> >
>> >
>> > ...objects that...
>> >
>> >   javadoc: error - module org.test.firstmodule not found.
>> >
>> >
>> > Clearly, I've wandered off into the tall weeds. I would appreciate 
>> > your advice and, if possible, a pointer to a primer on this topic.
>> >
>> > Thanks,
>> > -Rick
>> >
>>
>>
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180530/97abbdfe/attachment.html>