From kumar.x.srinivasan at oracle.com  Mon Nov  6 21:48:01 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Mon, 06 Nov 2017 13:48:01 -0800
Subject: RFR: JDK-8190295: Introduce a new Table builder class
In-Reply-To: <59F3BA6D.1040106@oracle.com>
References: <59F3BA6D.1040106@oracle.com>
Message-ID: <5A00D891.30102@oracle.com>


Hi Jon,

This is an enormous improvement and simplification!. Thanks!

Table.java:

304      * <li>The prefix should probably be a value such that the genenrated ids cannot

s/genenrated/generated/


The previous block is ternary operation, would make it nicer if this is 
also so.

             HtmlTree cell;
             if ((colIndex) == rowScopeColumnIndex) {
                 cell = HtmlTree.TH(cellStyle, "row", c);
             } else {
                 cell = HtmlTree.TD(cellStyle, c);
             }

final HtmlTree cell = HtmlTree.TH(cellStyle, "row", c)
             ? HtmlTree.TH(cellStyle, "row", c)
             : HtmlTree.TD(cellStyle, c);



AbstractMemberWriter.java

+                TypeElement te = utils.getEnclosingTypeElement(element); // is this different from typeElement?

I ran a quick test, and encountered several test failures, the reason is 
ClassUseWriter uses this method,
and it creates  AbstractMemberWriter with typeElement = null, via
     public AbstractMemberWriter(SubWriterHolderWriter writer) {
         this(writer, null);
     }
and thus typeElement could be a null, the following might save some cpu 
cycles,
  I verified all tests pass and the comparison tests also pass.

+                TypeElement te = typeElement == null
+                        ? utils.getEnclosingTypeElement(element)
+                        : typeElement;


There were other details we discussed offlist, and that clarifies the 
questions I had,
regarding Table.java. Most of this is in Bhavesh's expertise, I will 
leave it to him.

Kumar


> Please review the following change, to replace the code to create HTML 
> tables with a new
> builder-style Table class. With the exception of some minor 
> differences (bug fixes) on
> the deprecated-list page, the generated output should be unchanged for 
> now, although
> we may want to remove some backwards-compatibility hacks at some point 
> in the future
> to make all tables be more uniform when appropriate.
>
> Before reading the detailed changes in the modified files, you might 
> want to start by
> reviewing the new Table class.
>
> JBS: https://bugs.openjdk.java.net/browse/JDK-8190295
> Webrev: http://cr.openjdk.java.net/~jjg/8190295/webrev.00/
>
>
> Notes:
>
> (Various files)
> Stuff that has been deleted has generally moved in some form or other 
> into the new Table class
> or otherwise made redundant.
>
> AbstractMemberWriter:118-138
> Previously, the state defining the table was indirectly managed in the 
> MemberSummaryBuilder
> class via tableContents and counter (uugh.) Now, the state is kept in 
> the AbstractMemberWriter
> and lazily created by getSummaryTable, line 120.
>
> AbstractMemberWriter:433-437
> Here's a relatively simple example of creating a Table, new-style.
> The table is created (433-437), rows are added (463) and the HTML 
> generated (465)
> Other Tables are created in *WriterImpl classes.
>
> AbstractMemberWriter: old lines 535-553
> Anything to do with TableTabs is now mostly hidden inside the Table 
> class, driven by
> addTab calls when the Table is initialized.
>
> AbstractMemberWriter:583-592
> The lines are called by the MemberSummaryBuilder to conclude its work 
> on the table.
>
> DeprecatedListWriter:
> There is a small, deliberate (bug fix?) change in behavior here. 
> Previously, modules
> in the deprecated list used the colFirst style, and other types used 
> colDeprecatedItemName.
> Now, everything uses the same style, colDeprecatedItemName. It didn't 
> seem worth
> fixing for the old bad behavior. Also note that some cells were 
> omitted from the table,
> causing inconsistent visual appear of the striping. That is also fixed.
>
> HtmlDocletWriter:2548
> This is made available, for now. The script item itself is in 
> HtmlWriter (uugh). Long term,
> this should move into a new Head class (builder for <head> element)
>
> MethodWriterImpl.java:258-278
> This is definitely the most exciting part of this work. This is the 
> client-side  replacement for
> all the previous code to manage table tabs. Now, each tab is just a 
> method call with a
> name and a predicate.
>
> ModuleIndexWriter.java:135-141
> Following on from the previous comment, here in ModuleIndexWriter, and 
> corresponding code
> in PackageIndexWriter, we have a dynamically added set of tabs, based 
> on command line options.
>
> ModuleWriterImpl.java:635-648
> For now, for compatibility the rows are added in the same order as 
> before.
> Going forward, we might want to add the rows in overall sorted order.
>
> PropertyWriterImpl.java:234-245
> Because we create differently configures tables for properties and 
> methods, one without tabs, one with,
> it falls out of the design that the rows in the properties table don't 
> get "ids", thus avoiding the earlier
> "duplicate id" problem.
>
> Table.java:
> The new class that does all the work. It's reasonably well commented, 
> so nothing to add here.
>
> -- Jon
>


From kumar.x.srinivasan at oracle.com  Tue Nov  7 02:09:42 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Mon, 06 Nov 2017 18:09:42 -0800
Subject: Fwd: RFR: 8190552/8185985: Augment the Compiler API tree ;  Html
 files in doc-files directories should be wrapped
In-Reply-To: <5A0114A1.7080909@oracle.com>
References: <5A0114A1.7080909@oracle.com>
Message-ID: <5A0115E6.3070509@oracle.com>

Hello,

Please review fix to augment the Compiler API tree to represent the 
entire HTML content of a file, please see bug [1] and webrev [2].
The above are required to implement the bug [3] and webrev [4], please 
review these as well.

Please note these patches exist as mq patches in my repo, and will be 
pushed as two discrete changesets.

Thanks Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8190552
[2] http://cr.openjdk.java.net/~ksrini/8190552/webrev.00/

[3] https://bugs.openjdk.java.net/browse/JDK-8185985
[4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/



From jonathan.gibbons at oracle.com  Tue Nov  7 02:17:28 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 06 Nov 2017 18:17:28 -0800
Subject: RFR: JDK-8190295: Introduce a new Table builder class
In-Reply-To: <5A00D891.30102@oracle.com>
References: <59F3BA6D.1040106@oracle.com> <5A00D891.30102@oracle.com>
Message-ID: <5A0117B8.5080504@oracle.com>

Kumar,

Thank you for your feedback. I've made the changes you suggested, and 
included the proposal
as part of a series of related changes to generally cleanup more of the 
same.

The overall webrev is now at
     http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/

which contains a series of webrevs as follows:

https://bugs.openjdk.java.net/browse/JDK-8190295
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.tables/index.html
changeset:   47482:d222b617b9d2
tag:         tables
user:        jjg
date:        Mon Nov 06 17:17:07 2017 -0800
summary:     8190295: Introduce a new Table builder class

https://bugs.openjdk.java.net/browse/JDK-8190818
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.scripts/index.html
changeset:   47483:875dd666843f
tag:         scripts
user:        jjg
date:        Mon Nov 06 17:18:34 2017 -0800
summary:     8190818: Introduce a new Script builder class

https://bugs.openjdk.java.net/browse/JDK-8190819
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmlDocument/index.html
changeset:   47484:aaf2675c4f4b
tag:         htmlDocument
user:        jjg
date:        Mon Nov 06 17:19:06 2017 -0800
summary:     8190819: Merge HtmlWriter into HtmlDocument

https://bugs.openjdk.java.net/browse/JDK-8190820
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.head/index.html
changeset:   47485:ca0c08593f7a
tag:         head
user:        jjg
date:        Mon Nov 06 17:19:28 2017 -0800
summary:     8190820: Introduce a new Head builder class

https://bugs.openjdk.java.net/browse/JDK-8190821
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.links/index.html
changeset:   47486:3e139d148884
tag:         links
user:        jjg
date:        Mon Nov 06 17:19:47 2017 -0800
summary:     8190821: Introduce a new Links builder class

https://bugs.openjdk.java.net/browse/JDK-8190822
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.linkInfoImplStylename/index.html
changeset:   47487:762be115f89a
tag:         linkInfoImplStylename
user:        jjg
date:        Mon Nov 06 17:20:49 2017 -0800
summary:     8190822: Remove dead code that could lead to invalid HTML

https://bugs.openjdk.java.net/browse/JDK-8190824
http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmldocwriter/index.html
changeset:   47488:c09c658d94b3
tag:         htmldocwriter
tag:         qtip
tag:         tip
user:        jjg
date:        Mon Nov 06 17:21:00 2017 -0800
summary:     8190824: Eliminate HtmlDocWriter

The first webrev (for Table.java) is the biggie. The others are all much 
simpler.

-- Jon

On 11/06/2017 01:48 PM, Kumar Srinivasan wrote:
>
> Hi Jon,
>
> This is an enormous improvement and simplification!. Thanks!
>
> Table.java:
>
> 304      * <li>The prefix should probably be a value such that the 
> genenrated ids cannot
>
> s/genenrated/generated/
>
>
> The previous block is ternary operation, would make it nicer if this 
> is also so.
>
>             HtmlTree cell;
>             if ((colIndex) == rowScopeColumnIndex) {
>                 cell = HtmlTree.TH(cellStyle, "row", c);
>             } else {
>                 cell = HtmlTree.TD(cellStyle, c);
>             }
>
> final HtmlTree cell = HtmlTree.TH(cellStyle, "row", c)
>             ? HtmlTree.TH(cellStyle, "row", c)
>             : HtmlTree.TD(cellStyle, c);
>
>
>
> AbstractMemberWriter.java
>
> +                TypeElement te = 
> utils.getEnclosingTypeElement(element); // is this different from 
> typeElement?
>
> I ran a quick test, and encountered several test failures, the reason 
> is ClassUseWriter uses this method,
> and it creates  AbstractMemberWriter with typeElement = null, via
>     public AbstractMemberWriter(SubWriterHolderWriter writer) {
>         this(writer, null);
>     }
> and thus typeElement could be a null, the following might save some 
> cpu cycles,
>  I verified all tests pass and the comparison tests also pass.
>
> +                TypeElement te = typeElement == null
> +                        ? utils.getEnclosingTypeElement(element)
> +                        : typeElement;
>
>
> There were other details we discussed offlist, and that clarifies the 
> questions I had,
> regarding Table.java. Most of this is in Bhavesh's expertise, I will 
> leave it to him.
>
> Kumar
>
>
>> Please review the following change, to replace the code to create 
>> HTML tables with a new
>> builder-style Table class. With the exception of some minor 
>> differences (bug fixes) on
>> the deprecated-list page, the generated output should be unchanged 
>> for now, although
>> we may want to remove some backwards-compatibility hacks at some 
>> point in the future
>> to make all tables be more uniform when appropriate.
>>
>> Before reading the detailed changes in the modified files, you might 
>> want to start by
>> reviewing the new Table class.
>>
>> JBS: https://bugs.openjdk.java.net/browse/JDK-8190295
>> Webrev: http://cr.openjdk.java.net/~jjg/8190295/webrev.00/
>>
>>
>> Notes:
>>
>> (Various files)
>> Stuff that has been deleted has generally moved in some form or other 
>> into the new Table class
>> or otherwise made redundant.
>>
>> AbstractMemberWriter:118-138
>> Previously, the state defining the table was indirectly managed in 
>> the MemberSummaryBuilder
>> class via tableContents and counter (uugh.) Now, the state is kept in 
>> the AbstractMemberWriter
>> and lazily created by getSummaryTable, line 120.
>>
>> AbstractMemberWriter:433-437
>> Here's a relatively simple example of creating a Table, new-style.
>> The table is created (433-437), rows are added (463) and the HTML 
>> generated (465)
>> Other Tables are created in *WriterImpl classes.
>>
>> AbstractMemberWriter: old lines 535-553
>> Anything to do with TableTabs is now mostly hidden inside the Table 
>> class, driven by
>> addTab calls when the Table is initialized.
>>
>> AbstractMemberWriter:583-592
>> The lines are called by the MemberSummaryBuilder to conclude its work 
>> on the table.
>>
>> DeprecatedListWriter:
>> There is a small, deliberate (bug fix?) change in behavior here. 
>> Previously, modules
>> in the deprecated list used the colFirst style, and other types used 
>> colDeprecatedItemName.
>> Now, everything uses the same style, colDeprecatedItemName. It didn't 
>> seem worth
>> fixing for the old bad behavior. Also note that some cells were 
>> omitted from the table,
>> causing inconsistent visual appear of the striping. That is also fixed.
>>
>> HtmlDocletWriter:2548
>> This is made available, for now. The script item itself is in 
>> HtmlWriter (uugh). Long term,
>> this should move into a new Head class (builder for <head> element)
>>
>> MethodWriterImpl.java:258-278
>> This is definitely the most exciting part of this work. This is the 
>> client-side  replacement for
>> all the previous code to manage table tabs. Now, each tab is just a 
>> method call with a
>> name and a predicate.
>>
>> ModuleIndexWriter.java:135-141
>> Following on from the previous comment, here in ModuleIndexWriter, 
>> and corresponding code
>> in PackageIndexWriter, we have a dynamically added set of tabs, based 
>> on command line options.
>>
>> ModuleWriterImpl.java:635-648
>> For now, for compatibility the rows are added in the same order as 
>> before.
>> Going forward, we might want to add the rows in overall sorted order.
>>
>> PropertyWriterImpl.java:234-245
>> Because we create differently configures tables for properties and 
>> methods, one without tabs, one with,
>> it falls out of the design that the rows in the properties table 
>> don't get "ids", thus avoiding the earlier
>> "duplicate id" problem.
>>
>> Table.java:
>> The new class that does all the work. It's reasonably well commented, 
>> so nothing to add here.
>>
>> -- Jon
>>
>


From jonathan.gibbons at oracle.com  Tue Nov  7 23:15:53 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 07 Nov 2017 15:15:53 -0800
Subject: Fwd: RFR: 8190552/8185985: Augment the Compiler API tree ; Html
 files in doc-files directories should be wrapped
In-Reply-To: <5A0115E6.3070509@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
Message-ID: <5A023EA9.8090509@oracle.com>


[1] https://bugs.openjdk.java.net/browse/JDK-8190552

src/jdk.compiler/share/classes/com/sun/source/doctree/DocTypeTree.java
line 32: typo: @lt; should be &lt;    >  should be &gt;

JavacTrees.java, 1041, 1042, duplicate call
> 1040         DocCommentTree docCommentTree = getDocCommentTree(jfo);
> 1041         docCommentTree = getDocCommentTree(jfo);

In DocCommentParser, the inPhase field can be reduced to a parameter on 
blockComment.
Also, the following replacement for 191-208 is more robust in the face 
of malformed docs:

  191                     if (isFileContent) {
  192                         switch (inPhase) {
  193                             case PREAMBLE:
				     if (peek("body") == PeekKind.OPEN) {
  194                                     trees.add(html());
  195                                     if (textStart == -1) {
  196                                         textStart = bp;
  197                                         lastNonWhite = -1;
  198                                     }
  199                                     // mark this as the start, for processing purposes
  200                                     newline = true;
  201                                     break loop;
                                      }
                                      break;
  202                             case BLOCK:
                                      if(peek("body") == PeekKind.CLOSE) {
  203                                     addPendingText(trees, lastNonWhite);
  204                                     break loop;
                                      }
                                      break;
  205                             default:
  206                                 // fall through
  207                         }
  208                     }

(As a further simplification, you could even make "peek" be "boolean 
peek(String)" and handle the / in the impl of peek, thus eliminating 
PeekKind.)


DCTree: 161-165
Format the new lines like the preceding lines (3-line form).

DCTree: 303,305
Use "text" instead of "body" consistently

test/langtools/tools/javac/doctree/dcapi/DocCommentTreeApiTester.java
line 196:  do you mean "incorrect" here?   do you mean"invalid"?
     (I don't know what it means to say "incorrect input document")
line 239: ditto

test/langtools/tools/javac/doctree/dcapi/overview0.html and friends
why do you still need the partial comment "<!--EXPECT_START"

test/langtools/tools/javac/doctree/dcapi/package.html
<!DOCTYPE...> must be the _first_ line of the file

On 11/06/2017 06:09 PM, Kumar Srinivasan wrote:
> Hello,
>
> Please review fix to augment the Compiler API tree to represent the 
> entire HTML content of a file, please see bug [1] and webrev [2].
> The above are required to implement the bug [3] and webrev [4], please 
> review these as well.
>
> Please note these patches exist as mq patches in my repo, and will be 
> pushed as two discrete changesets.
>
> Thanks Kumar
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
> [2] http://cr.openjdk.java.net/~ksrini/8190552/webrev.00/
>
> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/
>
>


From kumar.x.srinivasan at oracle.com  Wed Nov  8 04:09:51 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Tue, 07 Nov 2017 20:09:51 -0800
Subject: Fwd: RFR: 8190552/8185985: Augment the Compiler API tree ; Html
 files in doc-files directories should be wrapped
In-Reply-To: <5A023EA9.8090509@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A023EA9.8090509@oracle.com>
Message-ID: <5A02838F.4030400@oracle.com>

Jon,

Fixed your comments noted here:

updated full webrev:
http://cr.openjdk.java.net/~ksrini/8190552/webrev.01/

updated delta webrev
http://cr.openjdk.java.net/~ksrini/8190552/webrev.01/webrev.delta/


Thanks
Kumar

On 11/7/2017 3:15 PM, Jonathan Gibbons wrote:
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTypeTree.java
> line 32: typo: @lt; should be &lt;    >  should be &gt;
>
> JavacTrees.java, 1041, 1042, duplicate call
>> 1040         DocCommentTree docCommentTree = getDocCommentTree(jfo);
>> 1041         docCommentTree = getDocCommentTree(jfo);
>
> In DocCommentParser, the inPhase field can be reduced to a parameter 
> on blockComment.
> Also, the following replacement for 191-208 is more robust in the face 
> of malformed docs:
>
>  191                     if (isFileContent) {
>  192                         switch (inPhase) {
>  193                             case PREAMBLE:
>                      if (peek("body") == PeekKind.OPEN) {
>  194                                     trees.add(html());
>  195                                     if (textStart == -1) {
>  196                                         textStart = bp;
>  197                                         lastNonWhite = -1;
>  198                                     }
>  199                                     // mark this as the start, 
> for processing purposes
>  200                                     newline = true;
>  201                                     break loop;
>                                      }
>                                      break;
>  202                             case BLOCK:
>                                      if(peek("body") == PeekKind.CLOSE) {
>  203                                     addPendingText(trees, 
> lastNonWhite);
>  204                                     break loop;
>                                      }
>                                      break;
>  205                             default:
>  206                                 // fall through
>  207                         }
>  208                     }
>
> (As a further simplification, you could even make "peek" be "boolean 
> peek(String)" and handle the / in the impl of peek, thus eliminating 
> PeekKind.)
>
>
> DCTree: 161-165
> Format the new lines like the preceding lines (3-line form).
>
> DCTree: 303,305
> Use "text" instead of "body" consistently
>
> test/langtools/tools/javac/doctree/dcapi/DocCommentTreeApiTester.java
> line 196:  do you mean "incorrect" here?   do you mean"invalid"?
>     (I don't know what it means to say "incorrect input document")
> line 239: ditto
>
> test/langtools/tools/javac/doctree/dcapi/overview0.html and friends
> why do you still need the partial comment "<!--EXPECT_START"
>
> test/langtools/tools/javac/doctree/dcapi/package.html
> <!DOCTYPE...> must be the _first_ line of the file
>
> On 11/06/2017 06:09 PM, Kumar Srinivasan wrote:
>> Hello,
>>
>> Please review fix to augment the Compiler API tree to represent the 
>> entire HTML content of a file, please see bug [1] and webrev [2].
>> The above are required to implement the bug [3] and webrev [4], 
>> please review these as well.
>>
>> Please note these patches exist as mq patches in my repo, and will be 
>> pushed as two discrete changesets.
>>
>> Thanks Kumar
>>
>> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
>> [2] http://cr.openjdk.java.net/~ksrini/8190552/webrev.00/
>>
>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/
>>
>>
>


From jonathan.gibbons at oracle.com  Wed Nov  8 23:15:02 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 08 Nov 2017 15:15:02 -0800
Subject: Fwd: RFR: 8190552/8185985: Augment the Compiler API tree ; Html
 files in doc-files directories should be wrapped
In-Reply-To: <5A02838F.4030400@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A023EA9.8090509@oracle.com> <5A02838F.4030400@oracle.com>
Message-ID: <5A038FF6.3000607@oracle.com>

Looks good.  I like the cleanup in DocCommentParser.

The line line of the last file looks inconsistently weird, but as long 
as the checked in file is good, that is what matters.

-- Jon

On 11/07/2017 08:09 PM, Kumar Srinivasan wrote:
> Jon,
>
> Fixed your comments noted here:
>
> updated full webrev:
> http://cr.openjdk.java.net/~ksrini/8190552/webrev.01/
>
> updated delta webrev
> http://cr.openjdk.java.net/~ksrini/8190552/webrev.01/webrev.delta/
>
>
> Thanks
> Kumar
>
> On 11/7/2017 3:15 PM, Jonathan Gibbons wrote:
>>
>> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
>>
>> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTypeTree.java
>> line 32: typo: @lt; should be &lt;    >  should be &gt;
>>
>> JavacTrees.java, 1041, 1042, duplicate call
>>> 1040         DocCommentTree docCommentTree = getDocCommentTree(jfo);
>>> 1041         docCommentTree = getDocCommentTree(jfo);
>>
>> In DocCommentParser, the inPhase field can be reduced to a parameter 
>> on blockComment.
>> Also, the following replacement for 191-208 is more robust in the 
>> face of malformed docs:
>>
>>  191                     if (isFileContent) {
>>  192                         switch (inPhase) {
>>  193                             case PREAMBLE:
>>                      if (peek("body") == PeekKind.OPEN) {
>>  194                                     trees.add(html());
>>  195                                     if (textStart == -1) {
>>  196                                         textStart = bp;
>>  197                                         lastNonWhite = -1;
>>  198                                     }
>>  199                                     // mark this as the start, 
>> for processing purposes
>>  200                                     newline = true;
>>  201                                     break loop;
>>                                      }
>>                                      break;
>>  202                             case BLOCK:
>>                                      if(peek("body") == 
>> PeekKind.CLOSE) {
>>  203                                     addPendingText(trees, 
>> lastNonWhite);
>>  204                                     break loop;
>>                                      }
>>                                      break;
>>  205                             default:
>>  206                                 // fall through
>>  207                         }
>>  208                     }
>>
>> (As a further simplification, you could even make "peek" be "boolean 
>> peek(String)" and handle the / in the impl of peek, thus eliminating 
>> PeekKind.)
>>
>>
>> DCTree: 161-165
>> Format the new lines like the preceding lines (3-line form).
>>
>> DCTree: 303,305
>> Use "text" instead of "body" consistently
>>
>> test/langtools/tools/javac/doctree/dcapi/DocCommentTreeApiTester.java
>> line 196:  do you mean "incorrect" here?   do you mean"invalid"?
>>     (I don't know what it means to say "incorrect input document")
>> line 239: ditto
>>
>> test/langtools/tools/javac/doctree/dcapi/overview0.html and friends
>> why do you still need the partial comment "<!--EXPECT_START"
>>
>> test/langtools/tools/javac/doctree/dcapi/package.html
>> <!DOCTYPE...> must be the _first_ line of the file
>>
>> On 11/06/2017 06:09 PM, Kumar Srinivasan wrote:
>>> Hello,
>>>
>>> Please review fix to augment the Compiler API tree to represent the 
>>> entire HTML content of a file, please see bug [1] and webrev [2].
>>> The above are required to implement the bug [3] and webrev [4], 
>>> please review these as well.
>>>
>>> Please note these patches exist as mq patches in my repo, and will 
>>> be pushed as two discrete changesets.
>>>
>>> Thanks Kumar
>>>
>>> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
>>> [2] http://cr.openjdk.java.net/~ksrini/8190552/webrev.00/
>>>
>>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/
>>>
>>>
>>
>


From jonathan.gibbons at oracle.com  Thu Nov  9 01:12:22 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 08 Nov 2017 17:12:22 -0800
Subject: Fwd: RFR: 8190552/8185985: Augment the Compiler API tree ; Html
 files in doc-files directories should be wrapped
In-Reply-To: <5A0115E6.3070509@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
Message-ID: <5A03AB76.8000708@oracle.com>

Here's comments on the code (not looked at the tests yet).

On 11/06/2017 06:04 PM, Kumar Srinivasan wrote:
>
> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/ 

HtmlDocletWriter: line 451-493
I accept you have put the new code after the existing like-named method,
but we're still trying to de-clutter classes like HtmlDocletWriter.
The new method seems like a combination of two methods ...
one is new functionality to extract the TITLE from an HTML document,
and the other is a simple call onto the existing getWindowTitle.

I'm also not sure that the filename is a good default. But that being said,
TITLE is not an optional element in a HEAD section, and should always be
provided, and so a non-empty default may never normally be required.


HtmlDocletWriter: line 2495,2496
Suggest increasing indent of parameter list

WriterFactoryImpl: 244
You're in a class called "WriterFactoryImpl" and the method is named 
"getDocFilesWriter"
and yet it returns an object whose type is DocFilesHandler, instead of 
DocFilesWriter.
Just sayin'....

BaseConfiguration:378
Were you going to move this assignment later in the execution?

CommentUtils:183
When is the returned type not a PackageElement?
Why is the return type of the method not PackageElement?
If it can be something else, like a module element, should there be a 
check here?

CommentUtil:219-221
The comment requires some mental gymnastics to guess any possible meaning.
If you know what it means, can you rewrite it please?

OverviewElement
We definitely talked about removing any direct dependence on and storage of
BaseConfiguration.

WriterFactory
See comments for WriterFactoryImpl re: naming.

AnnotationTypeBuilder:31
ClassBuilder:31
ModuleSummaryBuilder:30
PackageSummaryBuilder:34
Illegal import. builders cannot depend on types in format-specific packages
(i.e. formats.html)  There needs to be an interface in the toolkit 
world, and
an impl of the interface in the formats.html world, the same as is done for
other Writer/WriterImpl pairs.

ModuleSummaryBuilder:120
You're very close to being able to support this. The PackageElement for
the DocletElement would be the unnamed package for the module.

DocFile:106
Grumble, why do you need this?  In general, the doclet world uses 
DocFile objects
not FileObjects

DocPaths:173-196
This class used to be sorted in case-equivalent alpha order. Somehow, 
these 'M'
fields and methods have ended up between 'P' and 'R'

StandardDocFileFactory
Again grumble that this is necessary, but I can see where this going

Utils
Who is now using these copyDirectory methods, since they don't check for 
HTML files?

DocFilesHandler.java
What about .HtMl ... in other words, get the extension and do a 
ignore-case check.
line 153: in time we'll want more from the <head> than just the title, 
so I think
getTitle belongs here.  Also, I don't think the title gets properly 
propagated to
the TITLE in the generated file.

DocFileElement:64
You want the unnamed package for the specific module (each module has 
its own unnamed package.)

DocletElement:83,84
You can't put types in the unnamed package of a named module, but javac 
(Symbol, etc)
does understand the concept, and so it is reasonable (in the API) to get 
the unnamed package
for a named module. You might need a workaround to get it, though.


-- Jon

From kumar.x.srinivasan at oracle.com  Thu Nov  9 03:33:35 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Wed, 08 Nov 2017 19:33:35 -0800
Subject: Fwd: RFR: 8190552/8185985: Augment the Compiler API tree ; Html
 files in doc-files directories should be wrapped
In-Reply-To: <5A038FF6.3000607@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A023EA9.8090509@oracle.com> <5A02838F.4030400@oracle.com>
 <5A038FF6.3000607@oracle.com>
Message-ID: <5A03CC8F.3030408@oracle.com>

Hi Jan, Jon,

Please review:
http://cr.openjdk.java.net/~ksrini/8190552/webrev.02/webrev.delta/
I have included Jan's patch to fix jshell test, add bugid to the tests,
I had missed adding that for the DocCommentParserApi test.

The full webrev is here containing everything for reference
http://cr.openjdk.java.net/~ksrini/8190552/webrev.02

Thanks
Kumar

On 11/8/2017 3:15 PM, Jonathan Gibbons wrote:
> Looks good.  I like the cleanup in DocCommentParser.
>
> The line line of the last file looks inconsistently weird, but as long 
> as the checked in file is good, that is what matters.
>
> -- Jon
>
> On 11/07/2017 08:09 PM, Kumar Srinivasan wrote:
>> Jon,
>>
>> Fixed your comments noted here:
>>
>> updated full webrev:
>> http://cr.openjdk.java.net/~ksrini/8190552/webrev.01/
>>
>> updated delta webrev
>> http://cr.openjdk.java.net/~ksrini/8190552/webrev.01/webrev.delta/
>>
>>
>> Thanks
>> Kumar
>>
>> On 11/7/2017 3:15 PM, Jonathan Gibbons wrote:
>>>
>>> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
>>>
>>> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTypeTree.java
>>> line 32: typo: @lt; should be &lt;    >  should be &gt;
>>>
>>> JavacTrees.java, 1041, 1042, duplicate call
>>>> 1040         DocCommentTree docCommentTree = getDocCommentTree(jfo);
>>>> 1041         docCommentTree = getDocCommentTree(jfo);
>>>
>>> In DocCommentParser, the inPhase field can be reduced to a parameter 
>>> on blockComment.
>>> Also, the following replacement for 191-208 is more robust in the 
>>> face of malformed docs:
>>>
>>>  191                     if (isFileContent) {
>>>  192                         switch (inPhase) {
>>>  193                             case PREAMBLE:
>>>                      if (peek("body") == PeekKind.OPEN) {
>>>  194                                     trees.add(html());
>>>  195                                     if (textStart == -1) {
>>>  196                                         textStart = bp;
>>>  197                                         lastNonWhite = -1;
>>>  198                                     }
>>>  199                                     // mark this as the start, 
>>> for processing purposes
>>>  200                                     newline = true;
>>>  201                                     break loop;
>>>                                      }
>>>                                      break;
>>>  202                             case BLOCK:
>>>                                      if(peek("body") == 
>>> PeekKind.CLOSE) {
>>>  203                                     addPendingText(trees, 
>>> lastNonWhite);
>>>  204                                     break loop;
>>>                                      }
>>>                                      break;
>>>  205                             default:
>>>  206                                 // fall through
>>>  207                         }
>>>  208                     }
>>>
>>> (As a further simplification, you could even make "peek" be "boolean 
>>> peek(String)" and handle the / in the impl of peek, thus eliminating 
>>> PeekKind.)
>>>
>>>
>>> DCTree: 161-165
>>> Format the new lines like the preceding lines (3-line form).
>>>
>>> DCTree: 303,305
>>> Use "text" instead of "body" consistently
>>>
>>> test/langtools/tools/javac/doctree/dcapi/DocCommentTreeApiTester.java
>>> line 196:  do you mean "incorrect" here?   do you mean"invalid"?
>>>     (I don't know what it means to say "incorrect input document")
>>> line 239: ditto
>>>
>>> test/langtools/tools/javac/doctree/dcapi/overview0.html and friends
>>> why do you still need the partial comment "<!--EXPECT_START"
>>>
>>> test/langtools/tools/javac/doctree/dcapi/package.html
>>> <!DOCTYPE...> must be the _first_ line of the file
>>>
>>> On 11/06/2017 06:09 PM, Kumar Srinivasan wrote:
>>>> Hello,
>>>>
>>>> Please review fix to augment the Compiler API tree to represent the 
>>>> entire HTML content of a file, please see bug [1] and webrev [2].
>>>> The above are required to implement the bug [3] and webrev [4], 
>>>> please review these as well.
>>>>
>>>> Please note these patches exist as mq patches in my repo, and will 
>>>> be pushed as two discrete changesets.
>>>>
>>>> Thanks Kumar
>>>>
>>>> [1] https://bugs.openjdk.java.net/browse/JDK-8190552
>>>> [2] http://cr.openjdk.java.net/~ksrini/8190552/webrev.00/
>>>>
>>>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>>>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/
>>>>
>>>>
>>>
>>
>


From kumar.x.srinivasan at oracle.com  Thu Nov  9 23:09:02 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Thu, 09 Nov 2017 15:09:02 -0800
Subject: RFR:8185985:Html files in doc-files directories should be wrapped
In-Reply-To: <5A03AB76.8000708@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A03AB76.8000708@oracle.com>
Message-ID: <5A04E00E.4040705@oracle.com>

Hi Jon,

[changed subj line to reflect the current review]
Full webrev:
http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/

Delta webrev:
http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/webrev.delta/

> Here's comments on the code (not looked at the tests yet).
>
> On 11/06/2017 06:04 PM, Kumar Srinivasan wrote:
>>
>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/ 
>
> HtmlDocletWriter: line 451-493
> I accept you have put the new code after the existing like-named method,
> but we're still trying to de-clutter classes like HtmlDocletWriter.
> The new method seems like a combination of two methods ...
> one is new functionality to extract the TITLE from an HTML document,
> and the other is a simple call onto the existing getWindowTitle.
>
> I'm also not sure that the filename is a good default. But that being 
> said,
> TITLE is not an optional element in a HEAD section, and should always be
> provided, and so a non-empty default may never normally be required.

  I have changed it to  use an empty string.


>
>
> HtmlDocletWriter: line 2495,2496
> Suggest increasing indent of parameter list

Done

>
> WriterFactoryImpl: 244
> You're in a class called "WriterFactoryImpl" and the method is named 
> "getDocFilesWriter"
> and yet it returns an object whose type is DocFilesHandler, instead of 
> DocFilesWriter.
> Just sayin'....

Fixed

>
> BaseConfiguration:378
> Were you going to move this assignment later in the execution?

Done


>
> CommentUtils:183
> When is the returned type not a PackageElement?
> Why is the return type of the method not PackageElement?
> If it can be something else, like a module element, should there be a 
> check here?

Fixed
>
> CommentUtil:219-221
> The comment requires some mental gymnastics to guess any possible 
> meaning.
> If you know what it means, can you rewrite it please?
Fixed

>
> OverviewElement
> We definitely talked about removing any direct dependence on and 
> storage of
> BaseConfiguration.

Fixed

>
> WriterFactory
> See comments for WriterFactoryImpl re: naming.
>
> AnnotationTypeBuilder:31
> ClassBuilder:31
> ModuleSummaryBuilder:30
> PackageSummaryBuilder:34
> Illegal import. builders cannot depend on types in format-specific 
> packages
> (i.e. formats.html)  There needs to be an interface in the toolkit 
> world, and
> an impl of the interface in the formats.html world, the same as is 
> done for
> other Writer/WriterImpl pairs.

Done

>
> ModuleSummaryBuilder:120
> You're very close to being able to support this. The PackageElement for
> the DocletElement would be the unnamed package for the module.

It all seems to work, for modules, however I have disabled it for now, 
added suitable
comments.

>
> DocFile:106
> Grumble, why do you need this?  In general, the doclet world uses 
> DocFile objects
> not FileObjects

FO needed  for DocTrees.

>
> DocPaths:173-196
> This class used to be sorted in case-equivalent alpha order. Somehow, 
> these 'M'
> fields and methods have ended up between 'P' and 'R'

Fixed.

>
> StandardDocFileFactory
> Again grumble that this is necessary, but I can see where this going
>
> Utils
> Who is now using these copyDirectory methods, since they don't check 
> for HTML files?

The doclet support files such as resources, jquery etc. Howeve please 
note the doc-files
are copied by its own copyDirectory logic.

>
> DocFilesHandler.java
> What about .HtMl ... in other words, get the extension and do a 
> ignore-case check.
> line 153: in time we'll want more from the <head> than just the title, 
> so I think
> getTitle belongs here.  Also, I don't think the title gets properly 
> propagated to
> the TITLE in the generated file.

moved it here and converted the file extension check as suggested. And 
it seems
to be propagated to the output, there are tests to check this.

>
> DocFileElement:64
> You want the unnamed package for the specific module (each module has 
> its own unnamed package.)

added a comment for future use.

>
> DocletElement:83,84
> You can't put types in the unnamed package of a named module, but 
> javac (Symbol, etc)
> does understand the concept, and so it is reasonable (in the API) to 
> get the unnamed package
> for a named module. You might need a workaround to get it, though.

Fixed comment

Thanks
Kumar

>
>
> -- Jon


From jonathan.gibbons at oracle.com  Wed Nov 15 23:21:23 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Nov 2017 15:21:23 -0800
Subject: javadoc -linksource with --module options doesn't generate
 src-html
In-Reply-To: <CAEgwkPfHR12U5isw75UXha_6QrEQ0XXoJA1=O_greV1LZXORbw@mail.gmail.com>
References: <CAEgwkPfHR12U5isw75UXha_6QrEQ0XXoJA1=O_greV1LZXORbw@mail.gmail.com>
Message-ID: <5A0CCBF3.7030105@oracle.com>



On 10/03/2017 10:43 AM, Nicolas Carranza wrote:
> Hi, I'm beginning to play with the JDK 9 and found that running 
> javadoc using the -linksource option combined with --module option (as 
> below) creates the javadoc with links targeting the html source files 
> but doesn't create the html source files (src-html directory). Is this 
> a bug? Thank you, and sorry if this isn't the place to post this question.
>
> > javadoc -linksource -d javadoc --module-source-path . --module java.base
> > java -version
> java version "9"
> Java(TM) SE Runtime Environment (build 9+181)
> Java HotSpot(TM) 64-Bit Server VM (build 9+181, mixed mode)
>

Nicolas,

That definitely sounds like a bug/oversight. I'll investigate, and 
create an issue to track this.

-- Jon

From jonathan.gibbons at oracle.com  Thu Nov 16 02:09:35 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 15 Nov 2017 18:09:35 -0800
Subject: javadoc -linksource with --module options doesn't generate
 src-html
In-Reply-To: <5A0CCBF3.7030105@oracle.com>
References: <CAEgwkPfHR12U5isw75UXha_6QrEQ0XXoJA1=O_greV1LZXORbw@mail.gmail.com>
 <5A0CCBF3.7030105@oracle.com>
Message-ID: <5A0CF35F.2020602@oracle.com>



On 11/15/2017 03:21 PM, Jonathan Gibbons wrote:
>
>
> On 10/03/2017 10:43 AM, Nicolas Carranza wrote:
>> Hi, I'm beginning to play with the JDK 9 and found that running 
>> javadoc using the -linksource option combined with --module option 
>> (as below) creates the javadoc with links targeting the html source 
>> files but doesn't create the html source files (src-html directory). 
>> Is this a bug? Thank you, and sorry if this isn't the place to post 
>> this question.
>>
>> > javadoc -linksource -d javadoc --module-source-path . --module 
>> java.base
>> > java -version
>> java version "9"
>> Java(TM) SE Runtime Environment (build 9+181)
>> Java HotSpot(TM) 64-Bit Server VM (build 9+181, mixed mode)
>>
>
> Nicolas,
>
> That definitely sounds like a bug/oversight. I'll investigate, and 
> create an issue to track this.
>
> -- Jon

Confirmed. Thanks for the report.
Filed https://bugs.openjdk.java.net/browse/JDK-8191381

-- Jon

From bhavesh.x.patel at oracle.com  Thu Nov 16 06:21:56 2017
From: bhavesh.x.patel at oracle.com (Bhavesh Patel)
Date: Wed, 15 Nov 2017 22:21:56 -0800
Subject: RFR: JDK-8190295: Introduce a new Table builder class
In-Reply-To: <5A0117B8.5080504@oracle.com>
References: <59F3BA6D.1040106@oracle.com> <5A00D891.30102@oracle.com>
 <5A0117B8.5080504@oracle.com>
Message-ID: <b0560ff4-faf6-7353-bece-8525d282220b@oracle.com>


Very good refactoring. Ok to push. Just a few minor suggestions. Also 
there could be some merge conflicts as I pushed the multiple stylesheet 
fix and I had done a few minor updated that were suggested. The patch 
that is applied to this fix does not have those changes e.g. In 
standard.properties <path> has been updated to <file>.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractIndexWriter.java*

Line 434: Should we move the prefix "I:" to Links.java and have a set 
method there? Then we can check in the getName() if the prefix needs to 
be generated. We have a similar prefix in Table.java so it would be 
consistent to handle it this way.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java*

Line 106: Do we need this anymore? Similar to getCaption() thats removed 
here. See comment on AnnotationTypeFieldWriterImpl.java

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeFieldWriterImpl.java

*Lines 207 - 210: Seems to be redundant/dead code. If you look at lines 
224 - 226, we set the summary there. Or else we can remove lines 224 
-226 and update line 233 to .setSummary(getTableSummary); as we have 
done in various other WriterImpl classes e.g. 
AnnotationTypeRequiredMemberWriterImpl.java, ConstructorWriterImpl.java, 
FieldWriterImpl.java etc. Same case with the caption as well.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriterImpl.java

*See comment on AnnotationTypeFieldWriterImpl.java. Inconsistency across 
WriterImpl classes.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java

*Live 250: Typo. 2 periods.*

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java

*Lines 466 & 485: param name "text" does not match the parameter in the 
method i.e. "caption".

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriterImpl.java*

See comment on AnnotationTypeFieldWriterImpl.java. Inconsistency across 
WriterImpl classes*.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java

*Lines 215 & 217: Commented out. Should it be removed?*
*******
*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Table.java*

- The copyright year should just be 2017 as its a new file.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java**
*
- The copyright year should just be 2017 as its a new file.

- Need a newline after line 78 to separate documentation comments from tags.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Links.java*

- The copyright year should just be 2017 as its a new file.

*src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java

*- The copyright year should just be 2017 as its a new file*.

*Regards,
Bhavesh.*
**
*
On 11/6/2017 6:17 PM, Jonathan Gibbons wrote:
> Kumar,
>
> Thank you for your feedback. I've made the changes you suggested, and 
> included the proposal
> as part of a series of related changes to generally cleanup more of 
> the same.
>
> The overall webrev is now at
> ??? http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/
>
> which contains a series of webrevs as follows:
>
> https://bugs.openjdk.java.net/browse/JDK-8190295
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.tables/index.html 
>
> changeset:?? 47482:d222b617b9d2
> tag:???????? tables
> user:??????? jjg
> date:??????? Mon Nov 06 17:17:07 2017 -0800
> summary:???? 8190295: Introduce a new Table builder class
>
> https://bugs.openjdk.java.net/browse/JDK-8190818
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.scripts/index.html 
>
> changeset:?? 47483:875dd666843f
> tag:???????? scripts
> user:??????? jjg
> date:??????? Mon Nov 06 17:18:34 2017 -0800
> summary:???? 8190818: Introduce a new Script builder class
>
> https://bugs.openjdk.java.net/browse/JDK-8190819
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmlDocument/index.html 
>
> changeset:?? 47484:aaf2675c4f4b
> tag:???????? htmlDocument
> user:??????? jjg
> date:??????? Mon Nov 06 17:19:06 2017 -0800
> summary:???? 8190819: Merge HtmlWriter into HtmlDocument
>
> https://bugs.openjdk.java.net/browse/JDK-8190820
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.head/index.html 
>
> changeset:?? 47485:ca0c08593f7a
> tag:???????? head
> user:??????? jjg
> date:??????? Mon Nov 06 17:19:28 2017 -0800
> summary:???? 8190820: Introduce a new Head builder class
>
> https://bugs.openjdk.java.net/browse/JDK-8190821
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.links/index.html 
>
> changeset:?? 47486:3e139d148884
> tag:???????? links
> user:??????? jjg
> date:??????? Mon Nov 06 17:19:47 2017 -0800
> summary:???? 8190821: Introduce a new Links builder class
>
> https://bugs.openjdk.java.net/browse/JDK-8190822
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.linkInfoImplStylename/index.html 
>
> changeset:?? 47487:762be115f89a
> tag:???????? linkInfoImplStylename
> user:??????? jjg
> date:??????? Mon Nov 06 17:20:49 2017 -0800
> summary:???? 8190822: Remove dead code that could lead to invalid HTML
>
> https://bugs.openjdk.java.net/browse/JDK-8190824
> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmldocwriter/index.html 
>
> changeset:?? 47488:c09c658d94b3
> tag:???????? htmldocwriter
> tag:???????? qtip
> tag:???????? tip
> user:??????? jjg
> date:??????? Mon Nov 06 17:21:00 2017 -0800
> summary:???? 8190824: Eliminate HtmlDocWriter
>
> The first webrev (for Table.java) is the biggie. The others are all 
> much simpler.
>
> -- Jon
>
> On 11/06/2017 01:48 PM, Kumar Srinivasan wrote:
>>
>> Hi Jon,
>>
>> This is an enormous improvement and simplification!. Thanks!
>>
>> Table.java:
>>
>> 304????? * <li>The prefix should probably be a value such that the 
>> genenrated ids cannot
>>
>> s/genenrated/generated/
>>
>>
>> The previous block is ternary operation, would make it nicer if this 
>> is also so.
>>
>> ??????????? HtmlTree cell;
>> ??????????? if ((colIndex) == rowScopeColumnIndex) {
>> ??????????????? cell = HtmlTree.TH(cellStyle, "row", c);
>> ??????????? } else {
>> ??????????????? cell = HtmlTree.TD(cellStyle, c);
>> ??????????? }
>>
>> final HtmlTree cell = HtmlTree.TH(cellStyle, "row", c)
>> ??????????? ? HtmlTree.TH(cellStyle, "row", c)
>> ??????????? : HtmlTree.TD(cellStyle, c);
>>
>>
>>
>> AbstractMemberWriter.java
>>
>> +??????????????? TypeElement te = 
>> utils.getEnclosingTypeElement(element); // is this different from 
>> typeElement?
>>
>> I ran a quick test, and encountered several test failures, the reason 
>> is ClassUseWriter uses this method,
>> and it creates? AbstractMemberWriter with typeElement = null, via
>> ??? public AbstractMemberWriter(SubWriterHolderWriter writer) {
>> ??????? this(writer, null);
>> ??? }
>> and thus typeElement could be a null, the following might save some 
>> cpu cycles,
>> ?I verified all tests pass and the comparison tests also pass.
>>
>> +??????????????? TypeElement te = typeElement == null
>> +??????????????????????? ? utils.getEnclosingTypeElement(element)
>> +??????????????????????? : typeElement;
>>
>>
>> There were other details we discussed offlist, and that clarifies the 
>> questions I had,
>> regarding Table.java. Most of this is in Bhavesh's expertise, I will 
>> leave it to him.
>>
>> Kumar
>>
>>
>>> Please review the following change, to replace the code to create 
>>> HTML tables with a new
>>> builder-style Table class. With the exception of some minor 
>>> differences (bug fixes) on
>>> the deprecated-list page, the generated output should be unchanged 
>>> for now, although
>>> we may want to remove some backwards-compatibility hacks at some 
>>> point in the future
>>> to make all tables be more uniform when appropriate.
>>>
>>> Before reading the detailed changes in the modified files, you might 
>>> want to start by
>>> reviewing the new Table class.
>>>
>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8190295
>>> Webrev: http://cr.openjdk.java.net/~jjg/8190295/webrev.00/
>>>
>>>
>>> Notes:
>>>
>>> (Various files)
>>> Stuff that has been deleted has generally moved in some form or 
>>> other into the new Table class
>>> or otherwise made redundant.
>>>
>>> AbstractMemberWriter:118-138
>>> Previously, the state defining the table was indirectly managed in 
>>> the MemberSummaryBuilder
>>> class via tableContents and counter (uugh.) Now, the state is kept 
>>> in the AbstractMemberWriter
>>> and lazily created by getSummaryTable, line 120.
>>>
>>> AbstractMemberWriter:433-437
>>> Here's a relatively simple example of creating a Table, new-style.
>>> The table is created (433-437), rows are added (463) and the HTML 
>>> generated (465)
>>> Other Tables are created in *WriterImpl classes.
>>>
>>> AbstractMemberWriter: old lines 535-553
>>> Anything to do with TableTabs is now mostly hidden inside the Table 
>>> class, driven by
>>> addTab calls when the Table is initialized.
>>>
>>> AbstractMemberWriter:583-592
>>> The lines are called by the MemberSummaryBuilder to conclude its 
>>> work on the table.
>>>
>>> DeprecatedListWriter:
>>> There is a small, deliberate (bug fix?) change in behavior here. 
>>> Previously, modules
>>> in the deprecated list used the colFirst style, and other types used 
>>> colDeprecatedItemName.
>>> Now, everything uses the same style, colDeprecatedItemName. It 
>>> didn't seem worth
>>> fixing for the old bad behavior. Also note that some cells were 
>>> omitted from the table,
>>> causing inconsistent visual appear of the striping. That is also fixed.
>>>
>>> HtmlDocletWriter:2548
>>> This is made available, for now. The script item itself is in 
>>> HtmlWriter (uugh). Long term,
>>> this should move into a new Head class (builder for <head> element)
>>>
>>> MethodWriterImpl.java:258-278
>>> This is definitely the most exciting part of this work. This is the 
>>> client-side? replacement for
>>> all the previous code to manage table tabs. Now, each tab is just a 
>>> method call with a
>>> name and a predicate.
>>>
>>> ModuleIndexWriter.java:135-141
>>> Following on from the previous comment, here in ModuleIndexWriter, 
>>> and corresponding code
>>> in PackageIndexWriter, we have a dynamically added set of tabs, 
>>> based on command line options.
>>>
>>> ModuleWriterImpl.java:635-648
>>> For now, for compatibility the rows are added in the same order as 
>>> before.
>>> Going forward, we might want to add the rows in overall sorted order.
>>>
>>> PropertyWriterImpl.java:234-245
>>> Because we create differently configures tables for properties and 
>>> methods, one without tabs, one with,
>>> it falls out of the design that the rows in the properties table 
>>> don't get "ids", thus avoiding the earlier
>>> "duplicate id" problem.
>>>
>>> Table.java:
>>> The new class that does all the work. It's reasonably well 
>>> commented, so nothing to add here.
>>>
>>> -- Jon
>>>
>>
>

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

From jonathan.gibbons at oracle.com  Thu Nov 16 20:00:40 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 16 Nov 2017 12:00:40 -0800
Subject: RFR: JDK-8190295: Introduce a new Table builder class
In-Reply-To: <b0560ff4-faf6-7353-bece-8525d282220b@oracle.com>
References: <59F3BA6D.1040106@oracle.com> <5A00D891.30102@oracle.com>
 <5A0117B8.5080504@oracle.com>
 <b0560ff4-faf6-7353-bece-8525d282220b@oracle.com>
Message-ID: <5A0DEE68.50700@oracle.com>

Bhavesh,

Responses inline.



On 11/15/2017 10:21 PM, Bhavesh Patel wrote:
>
> Very good refactoring. Ok to push. Just a few minor suggestions. Also 
> there could be some merge conflicts as I pushed the multiple 
> stylesheet fix and I had done a few minor updated that were suggested. 
> The patch that is applied to this fix does not have those changes e.g. 
> In standard.properties <path> has been updated to <file>.
>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractIndexWriter.java*
>
> Line 434: Should we move the prefix "I:" to Links.java and have a set 
> method there? Then we can check in the getName() if the prefix needs 
> to be generated. We have a similar prefix in Table.java so it would be 
> consistent to handle it this way.

Links is a singleton factory class, so although we could set a prefix 
string in the class, we wouldn't want it to apply to all anchors and 
links, meaning we would have to add extra overloads to say whether the 
prefix should be used or not. Moreover, this is very specific to the 
index world, so I'm inclined to leave it in the AbstractIndexWriter, at 
least for now.


>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java*
>
> Line 106: Do we need this anymore? Similar to getCaption() thats 
> removed here. See comment on AnnotationTypeFieldWriterImpl.java

I may have a go at trying to simplify this, (again?)  I seem to recall 
trying this before and there were some places where the method was being 
used from multiple places, but that may have been the table header 
(getTableHeader()) and not the summary. If I can get a 
build/test/compare to work, I'll do this; otherwise I will leave this 
for later


>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeFieldWriterImpl.java
>
> *Lines 207 - 210: Seems to be redundant/dead code. If you look at 
> lines 224 - 226, we set the summary there. Or else we can remove lines 
> 224 -226 and update line 233 to .setSummary(getTableSummary); as we 
> have done in various other WriterImpl classes e.g. 
> AnnotationTypeRequiredMemberWriterImpl.java, 
> ConstructorWriterImpl.java, FieldWriterImpl.java etc. Same case with 
> the caption as well.
>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriterImpl.java
>
> *See comment on AnnotationTypeFieldWriterImpl.java. Inconsistency 
> across WriterImpl classes.
>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java
>
> *Live 250: Typo. 2 periods.*
> *

Will fix

> *
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java
>
> *Lines 466 & 485: param name "text" does not match the parameter in 
> the method i.e. "caption".

Will fix

>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriterImpl.java*
>
> See comment on AnnotationTypeFieldWriterImpl.java. Inconsistency 
> across WriterImpl classes*.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java
>
> *Lines 215 & 217: Commented out. Should it be removed?*
> *

No, these are left in for phase 2, which will be to make all tables more 
consistent.
Right now, I'm placing greater emphasis on reducing change to generated 
output.

> **
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Table.java*
>
> - The copyright year should just be 2017 as its a new file.
>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java**
> *
> - The copyright year should just be 2017 as its a new file.
>
> - Need a newline after line 78 to separate documentation comments from 
> tags.

OK.

>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Links.java*
>
> - The copyright year should just be 2017 as its a new file.
>
> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java
>
> *- The copyright year should just be 2017 as its a new file*.
>
> *Regards,
> Bhavesh.*
> **
> *
> On 11/6/2017 6:17 PM, Jonathan Gibbons wrote:
>> Kumar,
>>
>> Thank you for your feedback. I've made the changes you suggested, and 
>> included the proposal
>> as part of a series of related changes to generally cleanup more of 
>> the same.
>>
>> The overall webrev is now at
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/
>>
>> which contains a series of webrevs as follows:
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190295
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.tables/index.html 
>>
>> changeset:   47482:d222b617b9d2
>> tag:         tables
>> user:        jjg
>> date:        Mon Nov 06 17:17:07 2017 -0800
>> summary:     8190295: Introduce a new Table builder class
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190818
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.scripts/index.html 
>>
>> changeset:   47483:875dd666843f
>> tag:         scripts
>> user:        jjg
>> date:        Mon Nov 06 17:18:34 2017 -0800
>> summary:     8190818: Introduce a new Script builder class
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190819
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmlDocument/index.html 
>>
>> changeset:   47484:aaf2675c4f4b
>> tag:         htmlDocument
>> user:        jjg
>> date:        Mon Nov 06 17:19:06 2017 -0800
>> summary:     8190819: Merge HtmlWriter into HtmlDocument
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190820
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.head/index.html 
>>
>> changeset:   47485:ca0c08593f7a
>> tag:         head
>> user:        jjg
>> date:        Mon Nov 06 17:19:28 2017 -0800
>> summary:     8190820: Introduce a new Head builder class
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190821
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.links/index.html 
>>
>> changeset:   47486:3e139d148884
>> tag:         links
>> user:        jjg
>> date:        Mon Nov 06 17:19:47 2017 -0800
>> summary:     8190821: Introduce a new Links builder class
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190822
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.linkInfoImplStylename/index.html 
>>
>> changeset:   47487:762be115f89a
>> tag:         linkInfoImplStylename
>> user:        jjg
>> date:        Mon Nov 06 17:20:49 2017 -0800
>> summary:     8190822: Remove dead code that could lead to invalid HTML
>>
>> https://bugs.openjdk.java.net/browse/JDK-8190824
>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmldocwriter/index.html 
>>
>> changeset:   47488:c09c658d94b3
>> tag:         htmldocwriter
>> tag:         qtip
>> tag:         tip
>> user:        jjg
>> date:        Mon Nov 06 17:21:00 2017 -0800
>> summary:     8190824: Eliminate HtmlDocWriter
>>
>> The first webrev (for Table.java) is the biggie. The others are all 
>> much simpler.
>>
>> -- Jon
>>
>> On 11/06/2017 01:48 PM, Kumar Srinivasan wrote:
>>>
>>> Hi Jon,
>>>
>>> This is an enormous improvement and simplification!. Thanks!
>>>
>>> Table.java:
>>>
>>> 304      * <li>The prefix should probably be a value such that the 
>>> genenrated ids cannot
>>>
>>> s/genenrated/generated/
>>>
>>>
>>> The previous block is ternary operation, would make it nicer if this 
>>> is also so.
>>>
>>>             HtmlTree cell;
>>>             if ((colIndex) == rowScopeColumnIndex) {
>>>                 cell = HtmlTree.TH(cellStyle, "row", c);
>>>             } else {
>>>                 cell = HtmlTree.TD(cellStyle, c);
>>>             }
>>>
>>> final HtmlTree cell = HtmlTree.TH(cellStyle, "row", c)
>>>             ? HtmlTree.TH(cellStyle, "row", c)
>>>             : HtmlTree.TD(cellStyle, c);
>>>
>>>
>>>
>>> AbstractMemberWriter.java
>>>
>>> +                TypeElement te = 
>>> utils.getEnclosingTypeElement(element); // is this different from 
>>> typeElement?
>>>
>>> I ran a quick test, and encountered several test failures, the 
>>> reason is ClassUseWriter uses this method,
>>> and it creates  AbstractMemberWriter with typeElement = null, via
>>>     public AbstractMemberWriter(SubWriterHolderWriter writer) {
>>>         this(writer, null);
>>>     }
>>> and thus typeElement could be a null, the following might save some 
>>> cpu cycles,
>>>  I verified all tests pass and the comparison tests also pass.
>>>
>>> +                TypeElement te = typeElement == null
>>> +                        ? utils.getEnclosingTypeElement(element)
>>> +                        : typeElement;
>>>
>>>
>>> There were other details we discussed offlist, and that clarifies 
>>> the questions I had,
>>> regarding Table.java. Most of this is in Bhavesh's expertise, I will 
>>> leave it to him.
>>>
>>> Kumar
>>>
>>>
>>>> Please review the following change, to replace the code to create 
>>>> HTML tables with a new
>>>> builder-style Table class. With the exception of some minor 
>>>> differences (bug fixes) on
>>>> the deprecated-list page, the generated output should be unchanged 
>>>> for now, although
>>>> we may want to remove some backwards-compatibility hacks at some 
>>>> point in the future
>>>> to make all tables be more uniform when appropriate.
>>>>
>>>> Before reading the detailed changes in the modified files, you 
>>>> might want to start by
>>>> reviewing the new Table class.
>>>>
>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8190295
>>>> Webrev: http://cr.openjdk.java.net/~jjg/8190295/webrev.00/
>>>>
>>>>
>>>> Notes:
>>>>
>>>> (Various files)
>>>> Stuff that has been deleted has generally moved in some form or 
>>>> other into the new Table class
>>>> or otherwise made redundant.
>>>>
>>>> AbstractMemberWriter:118-138
>>>> Previously, the state defining the table was indirectly managed in 
>>>> the MemberSummaryBuilder
>>>> class via tableContents and counter (uugh.) Now, the state is kept 
>>>> in the AbstractMemberWriter
>>>> and lazily created by getSummaryTable, line 120.
>>>>
>>>> AbstractMemberWriter:433-437
>>>> Here's a relatively simple example of creating a Table, new-style.
>>>> The table is created (433-437), rows are added (463) and the HTML 
>>>> generated (465)
>>>> Other Tables are created in *WriterImpl classes.
>>>>
>>>> AbstractMemberWriter: old lines 535-553
>>>> Anything to do with TableTabs is now mostly hidden inside the Table 
>>>> class, driven by
>>>> addTab calls when the Table is initialized.
>>>>
>>>> AbstractMemberWriter:583-592
>>>> The lines are called by the MemberSummaryBuilder to conclude its 
>>>> work on the table.
>>>>
>>>> DeprecatedListWriter:
>>>> There is a small, deliberate (bug fix?) change in behavior here. 
>>>> Previously, modules
>>>> in the deprecated list used the colFirst style, and other types 
>>>> used colDeprecatedItemName.
>>>> Now, everything uses the same style, colDeprecatedItemName. It 
>>>> didn't seem worth
>>>> fixing for the old bad behavior. Also note that some cells were 
>>>> omitted from the table,
>>>> causing inconsistent visual appear of the striping. That is also 
>>>> fixed.
>>>>
>>>> HtmlDocletWriter:2548
>>>> This is made available, for now. The script item itself is in 
>>>> HtmlWriter (uugh). Long term,
>>>> this should move into a new Head class (builder for <head> element)
>>>>
>>>> MethodWriterImpl.java:258-278
>>>> This is definitely the most exciting part of this work. This is the 
>>>> client-side  replacement for
>>>> all the previous code to manage table tabs. Now, each tab is just a 
>>>> method call with a
>>>> name and a predicate.
>>>>
>>>> ModuleIndexWriter.java:135-141
>>>> Following on from the previous comment, here in ModuleIndexWriter, 
>>>> and corresponding code
>>>> in PackageIndexWriter, we have a dynamically added set of tabs, 
>>>> based on command line options.
>>>>
>>>> ModuleWriterImpl.java:635-648
>>>> For now, for compatibility the rows are added in the same order as 
>>>> before.
>>>> Going forward, we might want to add the rows in overall sorted order.
>>>>
>>>> PropertyWriterImpl.java:234-245
>>>> Because we create differently configures tables for properties and 
>>>> methods, one without tabs, one with,
>>>> it falls out of the design that the rows in the properties table 
>>>> don't get "ids", thus avoiding the earlier
>>>> "duplicate id" problem.
>>>>
>>>> Table.java:
>>>> The new class that does all the work. It's reasonably well 
>>>> commented, so nothing to add here.
>>>>
>>>> -- Jon
>>>>
>>>
>>
>

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

From bhavesh.x.patel at oracle.com  Thu Nov 16 20:02:45 2017
From: bhavesh.x.patel at oracle.com (Bhavesh Patel)
Date: Thu, 16 Nov 2017 12:02:45 -0800
Subject: RFR: JDK-8190295: Introduce a new Table builder class
In-Reply-To: <5A0DEE68.50700@oracle.com>
References: <59F3BA6D.1040106@oracle.com> <5A00D891.30102@oracle.com>
 <5A0117B8.5080504@oracle.com>
 <b0560ff4-faf6-7353-bece-8525d282220b@oracle.com> <5A0DEE68.50700@oracle.com>
Message-ID: <3347a204-a062-471b-91e2-e5ffcf114293@oracle.com>


Ok. Thanks Jon. Good to be pushed.


On 11/16/2017 12:00 PM, Jonathan Gibbons wrote:
> Bhavesh,
>
> Responses inline.
>
>
>
> On 11/15/2017 10:21 PM, Bhavesh Patel wrote:
>>
>> Very good refactoring. Ok to push. Just a few minor suggestions. Also 
>> there could be some merge conflicts as I pushed the multiple 
>> stylesheet fix and I had done a few minor updated that were 
>> suggested. The patch that is applied to this fix does not have those 
>> changes e.g. In standard.properties <path> has been updated to <file>.
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractIndexWriter.java*
>>
>> Line 434: Should we move the prefix "I:" to Links.java and have a set 
>> method there? Then we can check in the getName() if the prefix needs 
>> to be generated. We have a similar prefix in Table.java so it would 
>> be consistent to handle it this way.
>
> Links is a singleton factory class, so although we could set a prefix 
> string in the class, we wouldn't want it to apply to all anchors and 
> links, meaning we would have to add extra overloads to say whether the 
> prefix should be used or not. Moreover, this is very specific to the 
> index world, so I'm inclined to leave it in the AbstractIndexWriter, 
> at least for now.
>
>
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java*
>>
>> Line 106: Do we need this anymore? Similar to getCaption() thats 
>> removed here. See comment on AnnotationTypeFieldWriterImpl.java
>
> I may have a go at trying to simplify this, (again?)? I seem to recall 
> trying this before and there were some places where the method was 
> being used from multiple places, but that may have been the table 
> header (getTableHeader()) and not the summary. If I can get a 
> build/test/compare to work, I'll do this; otherwise I will leave this 
> for later
>
>
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeFieldWriterImpl.java
>>
>> *Lines 207 - 210: Seems to be redundant/dead code. If you look at 
>> lines 224 - 226, we set the summary there. Or else we can remove 
>> lines 224 -226 and update line 233 to .setSummary(getTableSummary); 
>> as we have done in various other WriterImpl classes e.g. 
>> AnnotationTypeRequiredMemberWriterImpl.java, 
>> ConstructorWriterImpl.java, FieldWriterImpl.java etc. Same case with 
>> the caption as well.
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriterImpl.java
>>
>> *See comment on AnnotationTypeFieldWriterImpl.java. Inconsistency 
>> across WriterImpl classes.
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java
>>
>> *Live 250: Typo. 2 periods.*
>> *
>
> Will fix
>
>> *
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java
>>
>> *Lines 466 & 485: param name "text" does not match the parameter in 
>> the method i.e. "caption".
>
> Will fix
>
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriterImpl.java*
>>
>> See comment on AnnotationTypeFieldWriterImpl.java. Inconsistency 
>> across WriterImpl classes*.
>>
>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java
>>
>> *Lines 215 & 217: Commented out. Should it be removed?*
>> *
>
> No, these are left in for phase 2, which will be to make all tables 
> more consistent.
> Right now, I'm placing greater emphasis on reducing change to 
> generated output.
>
>> **
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Table.java*
>>
>> - The copyright year should just be 2017 as its a new file.
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java**
>> *
>> - The copyright year should just be 2017 as its a new file.
>>
>> - Need a newline after line 78 to separate documentation comments 
>> from tags.
>
> OK.
>
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Links.java*
>>
>> - The copyright year should just be 2017 as its a new file.
>>
>> *src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Script.java
>>
>> *- The copyright year should just be 2017 as its a new file*.
>>
>> *Regards,
>> Bhavesh.*
>> **
>> *
>> On 11/6/2017 6:17 PM, Jonathan Gibbons wrote:
>>> Kumar,
>>>
>>> Thank you for your feedback. I've made the changes you suggested, 
>>> and included the proposal
>>> as part of a series of related changes to generally cleanup more of 
>>> the same.
>>>
>>> The overall webrev is now at
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/
>>>
>>> which contains a series of webrevs as follows:
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190295
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.tables/index.html 
>>>
>>> changeset:?? 47482:d222b617b9d2
>>> tag:???????? tables
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:17:07 2017 -0800
>>> summary:???? 8190295: Introduce a new Table builder class
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190818
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.scripts/index.html 
>>>
>>> changeset:?? 47483:875dd666843f
>>> tag:???????? scripts
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:18:34 2017 -0800
>>> summary:???? 8190818: Introduce a new Script builder class
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190819
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmlDocument/index.html 
>>>
>>> changeset:?? 47484:aaf2675c4f4b
>>> tag:???????? htmlDocument
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:19:06 2017 -0800
>>> summary:???? 8190819: Merge HtmlWriter into HtmlDocument
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190820
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.head/index.html 
>>>
>>> changeset:?? 47485:ca0c08593f7a
>>> tag:???????? head
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:19:28 2017 -0800
>>> summary:???? 8190820: Introduce a new Head builder class
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190821
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.links/index.html 
>>>
>>> changeset:?? 47486:3e139d148884
>>> tag:???????? links
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:19:47 2017 -0800
>>> summary:???? 8190821: Introduce a new Links builder class
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190822
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.linkInfoImplStylename/index.html 
>>>
>>> changeset:?? 47487:762be115f89a
>>> tag:???????? linkInfoImplStylename
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:20:49 2017 -0800
>>> summary:???? 8190822: Remove dead code that could lead to invalid HTML
>>>
>>> https://bugs.openjdk.java.net/browse/JDK-8190824
>>> http://cr.openjdk.java.net/~jjg/8190295-etc/webrev.00/webrev.htmldocwriter/index.html 
>>>
>>> changeset:?? 47488:c09c658d94b3
>>> tag:???????? htmldocwriter
>>> tag:???????? qtip
>>> tag:???????? tip
>>> user:??????? jjg
>>> date:??????? Mon Nov 06 17:21:00 2017 -0800
>>> summary:???? 8190824: Eliminate HtmlDocWriter
>>>
>>> The first webrev (for Table.java) is the biggie. The others are all 
>>> much simpler.
>>>
>>> -- Jon
>>>
>>> On 11/06/2017 01:48 PM, Kumar Srinivasan wrote:
>>>>
>>>> Hi Jon,
>>>>
>>>> This is an enormous improvement and simplification!. Thanks!
>>>>
>>>> Table.java:
>>>>
>>>> 304????? * <li>The prefix should probably be a value such that the 
>>>> genenrated ids cannot
>>>>
>>>> s/genenrated/generated/
>>>>
>>>>
>>>> The previous block is ternary operation, would make it nicer if 
>>>> this is also so.
>>>>
>>>> ??????????? HtmlTree cell;
>>>> ??????????? if ((colIndex) == rowScopeColumnIndex) {
>>>> ??????????????? cell = HtmlTree.TH(cellStyle, "row", c);
>>>> ??????????? } else {
>>>> ??????????????? cell = HtmlTree.TD(cellStyle, c);
>>>> ??????????? }
>>>>
>>>> final HtmlTree cell = HtmlTree.TH(cellStyle, "row", c)
>>>> ??????????? ? HtmlTree.TH(cellStyle, "row", c)
>>>> ??????????? : HtmlTree.TD(cellStyle, c);
>>>>
>>>>
>>>>
>>>> AbstractMemberWriter.java
>>>>
>>>> +??????????????? TypeElement te = 
>>>> utils.getEnclosingTypeElement(element); // is this different from 
>>>> typeElement?
>>>>
>>>> I ran a quick test, and encountered several test failures, the 
>>>> reason is ClassUseWriter uses this method,
>>>> and it creates? AbstractMemberWriter with typeElement = null, via
>>>> ??? public AbstractMemberWriter(SubWriterHolderWriter writer) {
>>>> ??????? this(writer, null);
>>>> ??? }
>>>> and thus typeElement could be a null, the following might save some 
>>>> cpu cycles,
>>>> ?I verified all tests pass and the comparison tests also pass.
>>>>
>>>> +??????????????? TypeElement te = typeElement == null
>>>> +??????????????????????? ? utils.getEnclosingTypeElement(element)
>>>> +??????????????????????? : typeElement;
>>>>
>>>>
>>>> There were other details we discussed offlist, and that clarifies 
>>>> the questions I had,
>>>> regarding Table.java. Most of this is in Bhavesh's expertise, I 
>>>> will leave it to him.
>>>>
>>>> Kumar
>>>>
>>>>
>>>>> Please review the following change, to replace the code to create 
>>>>> HTML tables with a new
>>>>> builder-style Table class. With the exception of some minor 
>>>>> differences (bug fixes) on
>>>>> the deprecated-list page, the generated output should be unchanged 
>>>>> for now, although
>>>>> we may want to remove some backwards-compatibility hacks at some 
>>>>> point in the future
>>>>> to make all tables be more uniform when appropriate.
>>>>>
>>>>> Before reading the detailed changes in the modified files, you 
>>>>> might want to start by
>>>>> reviewing the new Table class.
>>>>>
>>>>> JBS: https://bugs.openjdk.java.net/browse/JDK-8190295
>>>>> Webrev: http://cr.openjdk.java.net/~jjg/8190295/webrev.00/
>>>>>
>>>>>
>>>>> Notes:
>>>>>
>>>>> (Various files)
>>>>> Stuff that has been deleted has generally moved in some form or 
>>>>> other into the new Table class
>>>>> or otherwise made redundant.
>>>>>
>>>>> AbstractMemberWriter:118-138
>>>>> Previously, the state defining the table was indirectly managed in 
>>>>> the MemberSummaryBuilder
>>>>> class via tableContents and counter (uugh.) Now, the state is kept 
>>>>> in the AbstractMemberWriter
>>>>> and lazily created by getSummaryTable, line 120.
>>>>>
>>>>> AbstractMemberWriter:433-437
>>>>> Here's a relatively simple example of creating a Table, new-style.
>>>>> The table is created (433-437), rows are added (463) and the HTML 
>>>>> generated (465)
>>>>> Other Tables are created in *WriterImpl classes.
>>>>>
>>>>> AbstractMemberWriter: old lines 535-553
>>>>> Anything to do with TableTabs is now mostly hidden inside the 
>>>>> Table class, driven by
>>>>> addTab calls when the Table is initialized.
>>>>>
>>>>> AbstractMemberWriter:583-592
>>>>> The lines are called by the MemberSummaryBuilder to conclude its 
>>>>> work on the table.
>>>>>
>>>>> DeprecatedListWriter:
>>>>> There is a small, deliberate (bug fix?) change in behavior here. 
>>>>> Previously, modules
>>>>> in the deprecated list used the colFirst style, and other types 
>>>>> used colDeprecatedItemName.
>>>>> Now, everything uses the same style, colDeprecatedItemName. It 
>>>>> didn't seem worth
>>>>> fixing for the old bad behavior. Also note that some cells were 
>>>>> omitted from the table,
>>>>> causing inconsistent visual appear of the striping. That is also 
>>>>> fixed.
>>>>>
>>>>> HtmlDocletWriter:2548
>>>>> This is made available, for now. The script item itself is in 
>>>>> HtmlWriter (uugh). Long term,
>>>>> this should move into a new Head class (builder for <head> element)
>>>>>
>>>>> MethodWriterImpl.java:258-278
>>>>> This is definitely the most exciting part of this work. This is 
>>>>> the client-side? replacement for
>>>>> all the previous code to manage table tabs. Now, each tab is just 
>>>>> a method call with a
>>>>> name and a predicate.
>>>>>
>>>>> ModuleIndexWriter.java:135-141
>>>>> Following on from the previous comment, here in ModuleIndexWriter, 
>>>>> and corresponding code
>>>>> in PackageIndexWriter, we have a dynamically added set of tabs, 
>>>>> based on command line options.
>>>>>
>>>>> ModuleWriterImpl.java:635-648
>>>>> For now, for compatibility the rows are added in the same order as 
>>>>> before.
>>>>> Going forward, we might want to add the rows in overall sorted order.
>>>>>
>>>>> PropertyWriterImpl.java:234-245
>>>>> Because we create differently configures tables for properties and 
>>>>> methods, one without tabs, one with,
>>>>> it falls out of the design that the rows in the properties table 
>>>>> don't get "ids", thus avoiding the earlier
>>>>> "duplicate id" problem.
>>>>>
>>>>> Table.java:
>>>>> The new class that does all the work. It's reasonably well 
>>>>> commented, so nothing to add here.
>>>>>
>>>>> -- Jon
>>>>>
>>>>
>>>
>>
>

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

From org.openjdk at io7m.com  Sat Nov 18 19:10:21 2017
From: org.openjdk at io7m.com (Mark Raynsford)
Date: Sat, 18 Nov 2017 19:10:21 +0000
Subject: The maven-javadoc-plugin on JDK 9
Message-ID: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>

Hello.

We're in the process of trying to get the maven-javadoc-plugin to work
correctly when generating documentation for modules. I have a simple
test case here that fails:

  https://github.com/io7m/maven-javadoc-bug-20171118

See the README.txt for the full build log and error messages.

I think, at a basic level, we want to do this:

  javadoc \
    -verbose \
    -sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
    --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c

But this of course fails with:

  javadoc: error - cannot use source path for multiple modules
  com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error

I note that there's --module-source-path option, so I'd expect the
following to work:

  javadoc \
    -verbose \
    --module-source-path \
    "a/src/main/java:b/src/main/java:c/src/main/java" \
    --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c

Unfortunately, this fails with:

javadoc: error - module com.io7m.bugs.a not found.
1 error

I can't get any more information out of the javadoc tool than that, so
I'm not sure exactly what's wrong. It's been suggested to me that the
problem might be that the --module-source-path expects each entry in the
path to be a directory containing a directory named after the
respective module, but that's obviously not going to happen in a
project with sources laid out in the Maven convention (unless we start
inserting symlinks everywhere).

What's the least painful way that we can update the javadoc plugin so
that it can generate JavaDoc for a given set of modules?

-- 
Mark Raynsford | http://www.io7m.com
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20171118/c4d62dc8/attachment.bin>

From jonathan.gibbons at oracle.com  Sun Nov 19 18:50:08 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Sun, 19 Nov 2017 10:50:08 -0800
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
Message-ID: <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>

If you are wanting to generate javadoc for multiple modules, you have 
two possibilities ...

 From the command line ...

Yes, you must use --module-source-path, but it allows a syntax for cases 
like this.
It does require that the source for each module must be "under" a 
directory with the same name as the module, but it needn't be "directly 
under". Like other paths, the module source path can be a series of 
entries separated by the standard platform path separator character (':' 
on Mac/Linux, ';' on Windows, etc). Each entry can be of the form

//path/to/module//*//relative/path/to/source/

In that, the '*' is the literal character '*' and it stands for the 
module name.? The character must be present as seen by javadoc/javac, 
meaning it should be escaped if necessary to pass it through your shell 
or anything else that might interpret it as a filesystem wildcard. The 
'*' is not a general wildcard; it is a marker to identify the 
module-name within the overall entry, to help separate the two parts 
before and after the '*'.

The /path/to/module/ should be a file system path to a directory 
containing one or more modules, each represented by a directory named 
for the module.

The /relative/path/to/source can be used to define how to locate the 
source directory under the module-named directory.

The /relative/path/to/source can be omitted if empty: if the source is 
directly under the module-named directory.

The '*' can be omitted if the /relative/path/to/source is omitted: i.e. 
if the '*' would be at the end of the entry.

In your case, it looks like the /relative/path/to/source is /src/main/java.


 From the API:

If you are using the javax.tools.DocumentationTool API and a 
JavaFileManager to invoke javadoc, there is API equivalent to the 
command line support, but in addition, there is a setLocationForModule 
method on StandardJavaFileManager that allows you to specify the exact 
file system path(s) for the source for each module you want to put on 
the module source path.



There is one other solution ... but it comes more in the "advanced" 
category, but may be reasonable in the context of the Maven plugin.
You can use
 ??? --patch-module /module-name/=/path/
to specify the source path for each module. You can give the option 
multiple times, but at most once for any given module.
You must still also set the module source path, but if you use 
--patch-module to specify the paths for all the modules you are 
interested in, the module source path can just point to an empty directory,
 ??? --module-source-path //path/to/empty/dir/
In this scenario, the --module-source-path option is just being used as 
a "marker option" to tell javadoc to accept multiple modules,

Hope that helps.

-- Jon


On 11/18/17 11:10 AM, Mark Raynsford wrote:
> Hello.
>
> We're in the process of trying to get the maven-javadoc-plugin to work
> correctly when generating documentation for modules. I have a simple
> test case here that fails:
>
>    https://github.com/io7m/maven-javadoc-bug-20171118
>
> See the README.txt for the full build log and error messages.
>
> I think, at a basic level, we want to do this:
>
>    javadoc \
>      -verbose \
>      -sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
>      --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>
> But this of course fails with:
>
>    javadoc: error - cannot use source path for multiple modules
>    com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error
>
> I note that there's --module-source-path option, so I'd expect the
> following to work:
>
>    javadoc \
>      -verbose \
>      --module-source-path \
>      "a/src/main/java:b/src/main/java:c/src/main/java" \
>      --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>
> Unfortunately, this fails with:
>
> javadoc: error - module com.io7m.bugs.a not found.
> 1 error
>
> I can't get any more information out of the javadoc tool than that, so
> I'm not sure exactly what's wrong. It's been suggested to me that the
> problem might be that the --module-source-path expects each entry in the
> path to be a directory containing a directory named after the
> respective module, but that's obviously not going to happen in a
> project with sources laid out in the Maven convention (unless we start
> inserting symlinks everywhere).
>
> What's the least painful way that we can update the javadoc plugin so
> that it can generate JavaDoc for a given set of modules?
>

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

From jonathan.gibbons at oracle.com  Sun Nov 19 21:24:45 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Sun, 19 Nov 2017 13:24:45 -0800
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <op.y9ywjkqzkdkhrr@desktop-2khsk44>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
 <op.y9ywjkqzkdkhrr@desktop-2khsk44>
Message-ID: <a2fd8aab-6206-4d96-42de-581667da80ed@oracle.com>

Robert,

For javac and javadoc, --patch-module is also permitted for sources; it 
was a late change/addition towards the end of JDK 9.

In the test case you are playing with, is com.io7m.bugs.c a package name 
as well as a module name?? If not, and if you think javadoc is 
misinterpreting the name as a package name, could it be that something 
is wrong with your --module option, which is presumably where that name 
appears on the command line.

I don't think it's the case here, but I'll also mention this ... javadoc 
(and javac) will want to see definitions of all symbols mentioned (e.g. 
imported) in source files you want to process. This is a since-forever 
property (and sometimes an annoying one). In time, it would be good to 
drop this. Until then, you can provide compiled/binary versions of any 
classes that you do not want to include in the documentation. If these 
classes are in totally separate modules, you can put those modules on 
the module path. If those classes are in modules that you are 
documenting, you'll need to put those compiled classes on the 
patch-module path, although with the source of the module.

-- Jon

On 11/19/17 12:29 PM, Robert Scholte wrote:
> Hi Jon,
>
> that's what I've tried to do, but when using Marks project as example 
> it fails with:
>
> [parsing completed 0ms]
> [loading /modules/java.base/module-info.class]
> Loading source files for package com.io7m.bugs.c...
> javadoc: error - No source files for package com.io7m.bugs.c
> 1 error
>
> I'm kind of surprised that --patch-module should work for sources, 
> although it seems to find the module descriptors.
>
> Docs say
> --patch-module module=file(file*)
> Overrides arguments in a module with classes and resources in JAR 
> files or directories.
>
> It is not referring to source folders, which could be the reason why I 
> got the error.
>
> Could it be that we're actually missing an argument for this case, 
> something like --patch-module-source?
>
> thanks,
> Robert
>
> On Sun, 19 Nov 2017 19:50:08 +0100, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com> wrote:
>
>     If you are wanting to generate javadoc for multiple modules, you
>     have two possibilities ...
>
>     From the command line ...
>
>     Yes, you must use --module-source-path, but it allows a syntax for
>     cases like this.
>     It does require that the source for each module must be "under" a
>     directory with the same name as the module, but it needn't be
>     "directly under". Like other paths, the module source path can be
>     a series of entries separated by the standard platform path
>     separator character (':' on Mac/Linux, ';' on Windows, etc). Each
>     entry can be of the form
>
>     //path/to/module//*//relative/path/to/source/
>
>     In that, the '*' is the literal character '*' and it stands for
>     the module name.? The character must be present as seen by
>     javadoc/javac, meaning it should be escaped if necessary to pass
>     it through your shell or anything else that might interpret it as
>     a filesystem wildcard. The '*' is not a general wildcard; it is a
>     marker to identify the module-name within the overall entry, to
>     help separate the two parts before and after the '*'.
>
>     The /path/to/module/ should be a file system path to a directory
>     containing one or more modules, each represented by a directory
>     named for the module.
>
>     The /relative/path/to/source can be used to define how to locate
>     the source directory under the module-named directory.
>
>     The /relative/path/to/source can be omitted if empty: if the
>     source is directly under the module-named directory.
>
>     The '*' can be omitted if the /relative/path/to/source is omitted:
>     i.e. if the '*' would be at the end of the entry.
>
>     In your case, it looks like the /relative/path/to/source is
>     /src/main/java.
>
>
>     From the API:
>
>     If you are using the javax.tools.DocumentationTool API and a
>     JavaFileManager to invoke javadoc, there is API equivalent to the
>     command line support, but in addition, there is a
>     setLocationForModule method on StandardJavaFileManager that allows
>     you to specify the exact file system path(s) for the source for
>     each module you want to put on the module source path.
>
>
>
>     There is one other solution ... but it comes more in the
>     "advanced" category, but may be reasonable in the context of the
>     Maven plugin.
>     You can use
>     ??? --patch-module /module-name/=/path/
>     to specify the source path for each module. You can give the
>     option multiple times, but at most once for any given module.
>     You must still also set the module source path, but if you use
>     --patch-module to specify the paths for all the modules you are
>     interested in, the module source path can just point to an empty
>     directory,
>     ??? --module-source-path //path/to/empty/dir/
>     In this scenario, the --module-source-path option is just being
>     used as a "marker option" to tell javadoc to accept multiple modules,
>
>     Hope that helps.
>
>     -- Jon
>
>
>     On 11/18/17 11:10 AM, Mark Raynsford wrote:
>>     Hello.
>>
>>     We're in the process of trying to get the maven-javadoc-plugin to work
>>     correctly when generating documentation for modules. I have a simple
>>     test case here that fails:
>>
>>        https://github.com/io7m/maven-javadoc-bug-20171118
>>
>>     See the README.txt for the full build log and error messages.
>>
>>     I think, at a basic level, we want to do this:
>>
>>        javadoc \
>>          -verbose \
>>          -sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
>>          --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>
>>     But this of course fails with:
>>
>>        javadoc: error - cannot use source path for multiple modules
>>        com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error
>>
>>     I note that there's --module-source-path option, so I'd expect the
>>     following to work:
>>
>>        javadoc \
>>          -verbose \
>>          --module-source-path \
>>          "a/src/main/java:b/src/main/java:c/src/main/java" \
>>          --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>
>>     Unfortunately, this fails with:
>>
>>     javadoc: error - module com.io7m.bugs.a not found.
>>     1 error
>>
>>     I can't get any more information out of the javadoc tool than that, so
>>     I'm not sure exactly what's wrong. It's been suggested to me that the
>>     problem might be that the --module-source-path expects each entry in the
>>     path to be a directory containing a directory named after the
>>     respective module, but that's obviously not going to happen in a
>>     project with sources laid out in the Maven convention (unless we start
>>     inserting symlinks everywhere).
>>
>>     What's the least painful way that we can update the javadoc plugin so
>>     that it can generate JavaDoc for a given set of modules?
>>
>
>
>
>

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

From org.openjdk at io7m.com  Sun Nov 19 19:36:11 2017
From: org.openjdk at io7m.com (Mark Raynsford)
Date: Sun, 19 Nov 2017 19:36:11 +0000
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
Message-ID: <20171119193611.062d5d17@copperhead.int.arc7.info>

'Ello.

Thanks for the detailed response!

On 2017-11-19T10:50:08 -0800
Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>
> There is one other solution ... but it comes more in the "advanced" 
> category, but may be reasonable in the context of the Maven plugin.
> You can use
>  ??? --patch-module /module-name/=/path/
> to specify the source path for each module. You can give the option 
> multiple times, but at most once for any given module.
> You must still also set the module source path, but if you use 
> --patch-module to specify the paths for all the modules you are 
> interested in, the module source path can just point to an empty directory,
>  ??? --module-source-path //path/to/empty/dir/
> In this scenario, the --module-source-path option is just being used as 
> a "marker option" to tell javadoc to accept multiple modules,

This one is almost certainly the one we'll go with. It assumes less
about the directory hierarchy than the other options, so it seems the
easiest to fit into the existing system.

-- 
Mark Raynsford | http://www.io7m.com

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20171119/50c13e53/attachment.bin>

From rfscholte at apache.org  Sun Nov 19 20:29:34 2017
From: rfscholte at apache.org (Robert Scholte)
Date: Sun, 19 Nov 2017 21:29:34 +0100
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
Message-ID: <op.y9ywjkqzkdkhrr@desktop-2khsk44>

Hi Jon,

that's what I've tried to do, but when using Marks project as example it  
fails with:

[parsing completed 0ms]
[loading /modules/java.base/module-info.class]
Loading source files for package com.io7m.bugs.c...
javadoc: error - No source files for package com.io7m.bugs.c
1 error

I'm kind of surprised that --patch-module should work for sources,  
although it seems to find the module descriptors.

Docs say
--patch-module module=file(file*)
Overrides arguments in a module with classes and resources in JAR files or  
directories.

It is not referring to source folders, which could be the reason why I got  
the error.

Could it be that we're actually missing an argument for this case,  
something like --patch-module-source?

thanks,
Robert

On Sun, 19 Nov 2017 19:50:08 +0100, Jonathan Gibbons  
<jonathan.gibbons at oracle.com> wrote:

>
> If you are wanting to generate javadoc for multiple modules, you have  
> two possibilities ...
>
> From the command line ...
>
> Yes, you must use --module-source-path, but it allows a syntax for cases  
> like this.
> It does require that the source for each module must be "under" a  
> directory with the same name as the module, but it needn't be "directly  
> >under". Like other paths, the module source path can be a series of  
> entries separated by the standard platform path separator character (':'  
> on >Mac/Linux, ';' on Windows, etc). Each entry can be of the form
>
>    /path/to/module/*/relative/path/to/source
>
> In that, the '*' is the literal character '*' and it stands for the  
> module name.  The character must be present as seen by javadoc/javac,  
> meaning it >should be escaped if necessary to pass it through your shell  
> or anything else that might interpret it as a filesystem wildcard. The  
> '*' is not a >general wildcard; it is a marker to identify the  
> module-name within the overall entry, to help separate the two parts  
> before and after the '*'.
> The /path/to/module/ should be a file system path to a directory  
> containing one or more modules, each represented by a directory named  
> for >the module.
>
> The /relative/path/to/source can be used to define how to locate the  
> source directory under the module-named directory.
>
> The /relative/path/to/source can be omitted if empty: if the source is  
> directly under the module-named directory.
>
> The '*' can be omitted if the /relative/path/to/source is omitted: i.e.  
> if the '*' would be at the end of the entry.
>
> In your case, it looks like the /relative/path/to/source is  
> /src/main/java.
>
>
>
> From the API:
>
> If you are using the javax.tools.DocumentationTool API and a  
> JavaFileManager to invoke javadoc, there is API equivalent to the  
> command line >support, but in addition, there is a setLocationForModule  
> method on StandardJavaFileManager that allows you to specify the exact  
> file system >path(s) for the source for each module you want to put on  
> the module source path.
>
>
> There is one other solution ... but it comes more in the "advanced"  
> category, but may be reasonable in the context of the Maven plugin.
> You can use   --patch-module module-name=pathto specify the source path  
> for each module. You can give the option multiple times, but at most  
> once for any given module.
> You must still also set the module source path, but if you use  
> --patch-module to specify the paths for all the modules you are  
> interested in, the >module source path can just point to an empty  
> directory,
>    --module-source-path /path/to/empty/dir
> In this scenario, the --module-source-path option is just being used as  
> a "marker option" to tell javadoc to accept multiple modules,
> Hope that helps.
>
> -- Jon
>
>
> On 11/18/17 11:10 AM, Mark Raynsford wrote:
>> Hello.
>>
>> We're in the process of trying to get the maven-javadoc-plugin to work
>> correctly when generating documentation for modules. I have a simple
>> test case here that fails:
>>
>>  https://github.com/io7m/maven-javadoc-bug-20171118
>>
>> See the README.txt for the full build log and error messages.
>>
>> I think, at a basic level, we want to do this:
>>
>>  javadoc \
>>    -verbose \
>>    -sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
>>    --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>
>> But this of course fails with:
>>
>>  javadoc: error - cannot use source path for multiple modules
>>  com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error
>>
>> I note that there's --module-source-path option, so I'd expect the
>> following to work:
>>
>>  javadoc \
>>    -verbose \
>>    --module-source-path \
>>    "a/src/main/java:b/src/main/java:c/src/main/java" \
>>    --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>
>> Unfortunately, this fails with:
>>
>> javadoc: error - module com.io7m.bugs.a not found.
>> 1 error
>>
>> I can't get any more information out of the javadoc tool than that, so
>> I'm not sure exactly what's wrong. It's been suggested to me that the
>> problem might be that the --module-source-path expects each entry in the
>> path to be a directory containing a directory named after the
>> respective module, but that's obviously not going to happen in a
>> project with sources laid out in the Maven convention (unless we start
>> inserting symlinks everywhere).
>>
>> What's the least painful way that we can update the javadoc plugin so
>> that it can generate JavaDoc for a given set of modules?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20171119/9a82d6fb/attachment.html>

From jonathan.gibbons at oracle.com  Mon Nov 20 20:30:40 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 20 Nov 2017 12:30:40 -0800
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <op.y90pw1qmkdkhrr@desktop-2khsk44>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
 <op.y9ywjkqzkdkhrr@desktop-2khsk44>
 <a2fd8aab-6206-4d96-42de-581667da80ed@oracle.com>
 <op.y90pw1qmkdkhrr@desktop-2khsk44>
Message-ID: <711ac8fa-e2d5-dd1b-a7ac-a08cb2436c3c@oracle.com>

That seems like a bug that needs to be fixed.

As well as applications, there are also service-provider modules, which 
deserve to be documented, but which may not export API.

-- Jon


On 11/20/17 12:01 PM, Robert Scholte wrote:
> Hi Jon,
>
> I've found the problem. ?The issue is that the module descriptor of c 
> doesn't export any packages.
> Considering c is an application, it makes sense because that code is 
> not shared for third parties.
> But what if you are using javadoc as documentation of your code?
>
> Can this be solved *without* adding exports to the module descriptor 
> just for javadoc purpose?
>
> "--show-packages all" still comes with the same error message.
>
> thanks,
> Robert
>
> On Sun, 19 Nov 2017 22:24:45 +0100, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com> wrote:
>
>     Robert,
>
>     For javac and javadoc, --patch-module is also permitted for
>     sources; it was a late change/addition towards the end of JDK 9.
>
>     In the test case you are playing with, is com.io7m.bugs.c a
>     package name as well as a module name?? If not, and if you think
>     javadoc is misinterpreting the name as a package name, could it be
>     that something is wrong with your --module option, which is
>     presumably where that name appears on the command line.
>
>     I don't think it's the case here, but I'll also mention this ...
>     javadoc (and javac) will want to see definitions of all symbols
>     mentioned (e.g. imported) in source files you want to process.
>     This is a since-forever property (and sometimes an annoying one).
>     In time, it would be good to drop this. Until then, you can
>     provide compiled/binary versions of any classes that you do not
>     want to include in the documentation. If these classes are in
>     totally separate modules, you can put those modules on the module
>     path. If those classes are in modules that you are documenting,
>     you'll need to put those compiled classes on the patch-module
>     path, although with the source of the module.
>
>     -- Jon
>
>     On 11/19/17 12:29 PM, Robert Scholte wrote:
>>     Hi Jon,
>>
>>     that's what I've tried to do, but when using Marks project as
>>     example it fails with:
>>
>>     [parsing completed 0ms]
>>     [loading /modules/java.base/module-info.class]
>>     Loading source files for package com.io7m.bugs.c...
>>     javadoc: error - No source files for package com.io7m.bugs.c
>>     1 error
>>
>>     I'm kind of surprised that --patch-module should work for
>>     sources, although it seems to find the module descriptors.
>>
>>     Docs say
>>     --patch-module module=file(file*)
>>     Overrides arguments in a module with classes and resources in JAR
>>     files or directories.
>>
>>     It is not referring to source folders, which could be the reason
>>     why I got the error.
>>
>>     Could it be that we're actually missing an argument for this
>>     case, something like --patch-module-source?
>>
>>     thanks,
>>     Robert
>>
>>     On Sun, 19 Nov 2017 19:50:08 +0100, Jonathan Gibbons
>>     <jonathan.gibbons at oracle.com> wrote:
>>
>>         If you are wanting to generate javadoc for multiple modules,
>>         you have two possibilities ...
>>
>>         From the command line ...
>>
>>         Yes, you must use --module-source-path, but it allows a
>>         syntax for cases like this.
>>         It does require that the source for each module must be
>>         "under" a directory with the same name as the module, but it
>>         needn't be "directly under". Like other paths, the module
>>         source path can be a series of entries separated by the
>>         standard platform path separator character (':' on Mac/Linux,
>>         ';' on Windows, etc). Each entry can be of the form
>>
>>         //path/to/module//*//relative/path/to/source/
>>
>>         In that, the '*' is the literal character '*' and it stands
>>         for the module name.? The character must be present as seen
>>         by javadoc/javac, meaning it should be escaped if necessary
>>         to pass it through your shell or anything else that might
>>         interpret it as a filesystem wildcard. The '*' is not a
>>         general wildcard; it is a marker to identify the module-name
>>         within the overall entry, to help separate the two parts
>>         before and after the '*'.
>>
>>         The /path/to/module/ should be a file system path to a
>>         directory containing one or more modules, each represented by
>>         a directory named for the module.
>>
>>         The /relative/path/to/source can be used to define how to
>>         locate the source directory under the module-named directory.
>>
>>         The /relative/path/to/source can be omitted if empty: if the
>>         source is directly under the module-named directory.
>>
>>         The '*' can be omitted if the /relative/path/to/source is
>>         omitted: i.e. if the '*' would be at the end of the entry.
>>
>>         In your case, it looks like the /relative/path/to/source is
>>         /src/main/java.
>>
>>
>>         From the API:
>>
>>         If you are using the javax.tools.DocumentationTool API and a
>>         JavaFileManager to invoke javadoc, there is API equivalent to
>>         the command line support, but in addition, there is a
>>         setLocationForModule method on StandardJavaFileManager that
>>         allows you to specify the exact file system path(s) for the
>>         source for each module you want to put on the module source path.
>>
>>
>>
>>         There is one other solution ... but it comes more in the
>>         "advanced" category, but may be reasonable in the context of
>>         the Maven plugin.
>>         You can use
>>         ??? --patch-module /module-name/=/path/
>>         to specify the source path for each module. You can give the
>>         option multiple times, but at most once for any given module.
>>         You must still also set the module source path, but if you
>>         use --patch-module to specify the paths for all the modules
>>         you are interested in, the module source path can just point
>>         to an empty directory,
>>         ??? --module-source-path //path/to/empty/dir/
>>         In this scenario, the --module-source-path option is just
>>         being used as a "marker option" to tell javadoc to accept
>>         multiple modules,
>>
>>         Hope that helps.
>>
>>         -- Jon
>>
>>
>>         On 11/18/17 11:10 AM, Mark Raynsford wrote:
>>>         Hello.
>>>
>>>         We're in the process of trying to get the maven-javadoc-plugin to work
>>>         correctly when generating documentation for modules. I have a simple
>>>         test case here that fails:
>>>
>>>            https://github.com/io7m/maven-javadoc-bug-20171118
>>>
>>>         See the README.txt for the full build log and error messages.
>>>
>>>         I think, at a basic level, we want to do this:
>>>
>>>            javadoc \
>>>              -verbose \
>>>              -sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
>>>              --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>>
>>>         But this of course fails with:
>>>
>>>            javadoc: error - cannot use source path for multiple modules
>>>            com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error
>>>
>>>         I note that there's --module-source-path option, so I'd expect the
>>>         following to work:
>>>
>>>            javadoc \
>>>              -verbose \
>>>              --module-source-path \
>>>              "a/src/main/java:b/src/main/java:c/src/main/java" \
>>>              --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>>
>>>         Unfortunately, this fails with:
>>>
>>>         javadoc: error - module com.io7m.bugs.a not found.
>>>         1 error
>>>
>>>         I can't get any more information out of the javadoc tool than that, so
>>>         I'm not sure exactly what's wrong. It's been suggested to me that the
>>>         problem might be that the --module-source-path expects each entry in the
>>>         path to be a directory containing a directory named after the
>>>         respective module, but that's obviously not going to happen in a
>>>         project with sources laid out in the Maven convention (unless we start
>>>         inserting symlinks everywhere).
>>>
>>>         What's the least painful way that we can update the javadoc plugin so
>>>         that it can generate JavaDoc for a given set of modules?
>>>
>>
>>
>>
>>
>
>
>
>

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

From rfscholte at apache.org  Mon Nov 20 20:01:39 2017
From: rfscholte at apache.org (Robert Scholte)
Date: Mon, 20 Nov 2017 21:01:39 +0100
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <a2fd8aab-6206-4d96-42de-581667da80ed@oracle.com>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
 <op.y9ywjkqzkdkhrr@desktop-2khsk44>
 <a2fd8aab-6206-4d96-42de-581667da80ed@oracle.com>
Message-ID: <op.y90pw1qmkdkhrr@desktop-2khsk44>

Hi Jon,

I've found the problem.  The issue is that the module descriptor of c  
doesn't export any packages.
Considering c is an application, it makes sense because that code is not  
shared for third parties.
But what if you are using javadoc as documentation of your code?

Can this be solved *without* adding exports to the module descriptor just  
for javadoc purpose?

"--show-packages all" still comes with the same error message.

thanks,
Robert

On Sun, 19 Nov 2017 22:24:45 +0100, Jonathan Gibbons  
<jonathan.gibbons at oracle.com> wrote:

>
> Robert,
>
> For javac and javadoc, --patch-module is also permitted for sources; it  
> was a late change/addition towards the end of JDK 9.
>
> In the test case you are playing with, is com.io7m.bugs.c a package name  
> as well as a module name?  If not, and if you think javadoc is  
> >misinterpreting the name as a package name, could it be that something  
> is wrong with your --module option, which is presumably where that >name  
> appears on the command line.
>
> I don't think it's the case here, but I'll also mention this ... javadoc  
> (and javac) will want to see definitions of all symbols mentioned (e.g.  
> >imported) in source files you want to process. This is a since-forever  
> property (and sometimes an annoying one). In time, it would be good to  
> >drop this. Until then, you can provide compiled/binary versions of any  
> classes that you do not want to include in the documentation. If these  
> >classes are in totally separate modules, you can put those modules on  
> the module path. If those classes are in modules that you are  
> >documenting, you'll need to put those compiled classes on the  
> patch-module path, although with the source of the module.
> -- Jon
>
> On 11/19/17 12:29 PM, Robert Scholte wrote:
>> Hi Jon,
>>
>> that's what I've tried to do, but when using Marks project as example  
>> it fails with:
>>
>> [parsing completed 0ms]
>> [loading /modules/java.base/module-info.class]
>> Loading source files for package com.io7m.bugs.c...
>> javadoc: error - No source files for package com.io7m.bugs.c
>> 1 error
>>
>> I'm kind of surprised that --patch-module should work for sources,  
>> although it seems to find the module descriptors.
>>
>> Docs say
>> --patch-module module=file(file*)
>> Overrides arguments in a module with classes and resources in JAR files  
>> or directories.
>>
>> It is not referring to source folders, which could be the reason why I  
>> got the error.
>>
>> Could it be that we're actually missing an argument for this case,  
>> something like --patch-module-source?
>>
>> thanks,
>> Robert
>>
>> On Sun, 19 Nov 2017 19:50:08 +0100, Jonathan Gibbons  
>> <jonathan.gibbons at oracle.com> wrote:
>>
>>>
>>> If you are wanting to generate javadoc for multiple modules, you have  
>>> two possibilities ...
>>>
>>> From the command line ...
>>>
>>> Yes, you must use --module-source-path, but it allows a syntax for  
>>> cases like this.
>>> It does require that the source for each module must be "under" a  
>>> directory with the same name as the module, but it needn't >>>be  
>>> "directly under". Like other paths, the module source path can be a  
>>> series of entries separated by the standard platform >>>path separator  
>>> character (':' on Mac/Linux, ';' on Windows, etc). Each entry can be  
>>> of the form
>>>
>>>    /path/to/module/*/relative/path/to/source
>>>
>>> In that, the '*' is the literal character '*' and it stands for the  
>>> module name.  The character must be present as seen by  
>>> javadoc/>>>javac, meaning it should be escaped if necessary to pass it  
>>> through your shell or anything else that might interpret it as a  
>>> >>>filesystem wildcard. The '*' is not a general wildcard; it is a  
>>> marker to identify the module-name within the overall entry, to help  
>>> >>>separate the two parts before and after the '*'.
>>> The /path/to/module/ should be a file system path to a directory  
>>> containing one or more modules, each represented by a >>>directory  
>>> named for the module.
>>>
>>> The /relative/path/to/source can be used to define how to locate the  
>>> source directory under the module-named directory.
>>>
>>> The /relative/path/to/source can be omitted if empty: if the source is  
>>> directly under the module-named directory.
>>>
>>> The '*' can be omitted if the /relative/path/to/source is omitted:  
>>> i.e. if the '*' would be at the end of the entry.
>>>
>>> In your case, it looks like the /relative/path/to/source is  
>>> /src/main/java.
>>>
>>>
>>>
>>> From the API:
>>>
>>> If you are using the javax.tools.DocumentationTool API and a  
>>> JavaFileManager to invoke javadoc, there is API equivalent to >>>the  
>>> command line support, but in addition, there is a setLocationForModule  
>>> method on StandardJavaFileManager that allows >>>you to specify the  
>>> exact file system path(s) for the source for each module you want to  
>>> put on the module source path.
>>>
>>>
>>> There is one other solution ... but it comes more in the "advanced"  
>>> category, but may be reasonable in the context of the >>>Maven plugin.
>>> You can use   --patch-module module-name=pathto specify the source  
>>> path for each module. You can give the option multiple times, but at  
>>> most once for any given module.
>>> You must still also set the module source path, but if you use  
>>> --patch-module to specify the paths for all the modules you are  
>>> >>>interested in, the module source path can just point to an empty  
>>> directory,
>>>    --module-source-path /path/to/empty/dir
>>> In this scenario, the --module-source-path option is just being used  
>>> as a "marker option" to tell javadoc to accept multiple >>>modules,
>>> Hope that helps.
>>>
>>> -- Jon
>>>
>>>
>>> On 11/18/17 11:10 AM, Mark Raynsford wrote:
>>>> Hello.
>>>>
>>>> We're in the process of trying to get the maven-javadoc-plugin to work
>>>> correctly when generating documentation for modules. I have a simple
>>>> test case here that fails:
>>>>
>>>>  https://github.com/io7m/maven-javadoc-bug-20171118
>>>>
>>>> See the README.txt for the full build log and error messages.
>>>>
>>>> I think, at a basic level, we want to do this:
>>>>
>>>>  javadoc \
>>>>    -verbose \
>>>>    -sourcepath "a/src/main/java:b/src/main/java:c/src/main/java" \
>>>>    --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>>>
>>>> But this of course fails with:
>>>>
>>>>  javadoc: error - cannot use source path for multiple modules
>>>>  com.io7m.bugs.a, com.io7m.bugs.b, com.io7m.bugs.c 1 error
>>>>
>>>> I note that there's --module-source-path option, so I'd expect the
>>>> following to work:
>>>>
>>>>  javadoc \
>>>>    -verbose \
>>>>    --module-source-path \
>>>>    "a/src/main/java:b/src/main/java:c/src/main/java" \
>>>>    --module com.io7m.bugs.a,com.io7m.bugs.b,com.io7m.bugs.c
>>>>
>>>> Unfortunately, this fails with:
>>>>
>>>> javadoc: error - module com.io7m.bugs.a not found.
>>>> 1 error
>>>>
>>>> I can't get any more information out of the javadoc tool than that, so
>>>> I'm not sure exactly what's wrong. It's been suggested to me that the
>>>> problem might be that the --module-source-path expects each entry in  
>>>> the
>>>> path to be a directory containing a directory named after the
>>>> respective module, but that's obviously not going to happen in a
>>>> project with sources laid out in the Maven convention (unless we start
>>>> inserting symlinks everywhere).
>>>>
>>>> What's the least painful way that we can update the javadoc plugin so
>>>> that it can generate JavaDoc for a given set of modules?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20171120/0168be90/attachment-0001.html>

From jonathan.gibbons at oracle.com  Mon Nov 20 20:33:33 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 20 Nov 2017 12:33:33 -0800
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <op.y90pw1qmkdkhrr@desktop-2khsk44>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
 <op.y9ywjkqzkdkhrr@desktop-2khsk44>
 <a2fd8aab-6206-4d96-42de-581667da80ed@oracle.com>
 <op.y90pw1qmkdkhrr@desktop-2khsk44>
Message-ID: <7c3835b1-52cc-1d47-378f-5a97c7d86865@oracle.com>

Does this mean we have a secondary bug, that the error message you got 
said "package" when it meant "module"?

-- Jon


On 11/20/17 12:01 PM, Robert Scholte wrote:
>
> javadoc: error - No source files for package com.io7m.bugs.c


From rfscholte at apache.org  Mon Nov 20 20:37:11 2017
From: rfscholte at apache.org (Robert Scholte)
Date: Mon, 20 Nov 2017 21:37:11 +0100
Subject: The maven-javadoc-plugin on JDK 9
In-Reply-To: <7c3835b1-52cc-1d47-378f-5a97c7d86865@oracle.com>
References: <20171118191021.2a3b3dc3@copperhead.int.arc7.info>
 <3dc10d0d-1375-ccbf-f9d9-1ffb6ba4e54e@oracle.com>
 <op.y9ywjkqzkdkhrr@desktop-2khsk44>
 <a2fd8aab-6206-4d96-42de-581667da80ed@oracle.com>
 <op.y90pw1qmkdkhrr@desktop-2khsk44>
 <7c3835b1-52cc-1d47-378f-5a97c7d86865@oracle.com>
Message-ID: <op.y90rj9dlkdkhrr@desktop-2khsk44>

I guess so :)

thanks,
Robert

ps. can you add the label apache-maven-found to the issues so we can  
easily follow progress?

On Mon, 20 Nov 2017 21:33:33 +0100, Jonathan Gibbons  
<jonathan.gibbons at oracle.com> wrote:

> Does this mean we have a secondary bug, that the error message you got  
> said "package" when it meant "module"?
>
> -- Jon
>
>
> On 11/20/17 12:01 PM, Robert Scholte wrote:
>>
>> javadoc: error - No source files for package com.io7m.bugs.c

From kumar.x.srinivasan at oracle.com  Mon Nov 20 23:41:10 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Mon, 20 Nov 2017 15:41:10 -0800
Subject: RFR: 8187588: Error generating using JDK 9 javadoc against a JDK
 8 source repository
Message-ID: <5A136816.5070202@oracle.com>

Hello,

Please review simple fix for [1]  webrev at [2].

Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8187588
[2] http://cr.openjdk.java.net/~ksrini/8187588/webrev.00/

From jonathan.gibbons at oracle.com  Mon Nov 20 23:46:24 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 20 Nov 2017 15:46:24 -0800
Subject: RFR: 8187588: Error generating using JDK 9 javadoc against a
 JDK 8 source repository
In-Reply-To: <5A136816.5070202@oracle.com>
References: <5A136816.5070202@oracle.com>
Message-ID: <5A136950.3070405@oracle.com>

Mostly OK.

Suggest removing repeated use of @modules. The first use of @modules is 
enough ... it can take a list of values, spread over multiple lines.

   28  * @modules jdk.compiler/com.sun.tools.javac.api
   29  *          jdk.compiler/com.sun.tools.javac.main
   30  *          jdk.javadoc/jdk.javadoc.internal.api
   31  *          jdk.javadoc/jdk.javadoc.internal.tool
   32  * @library /tools/lib


-- Jon


On 11/20/2017 03:41 PM, Kumar Srinivasan wrote:
> Hello,
>
> Please review simple fix for [1]  webrev at [2].
>
> Thanks
> Kumar
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8187588
> [2] http://cr.openjdk.java.net/~ksrini/8187588/webrev.00/


From kumar.x.srinivasan at oracle.com  Tue Nov 21 15:22:19 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Tue, 21 Nov 2017 07:22:19 -0800
Subject: RFR: 8180019: javadoc should treat failure to access URL as an error, 
 not a warning.
Message-ID: <5A1444AB.6020601@oracle.com>

Hello,

Please review this simple fix for [1], webrev at [2].

Thanks
Kumar

[1] https://bugs.openjdk.java.net/browse/JDK-8180019
[2] http://cr.openjdk.java.net/~ksrini/8180019/webrev.00/

From jonathan.gibbons at oracle.com  Tue Nov 21 19:04:43 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 21 Nov 2017 11:04:43 -0800
Subject: RFR: 8180019: javadoc should treat failure to access URL as an
 error, not a warning.
In-Reply-To: <5A1444AB.6020601@oracle.com>
References: <5A1444AB.6020601@oracle.com>
Message-ID: <5A1478CB.2060306@oracle.com>

OK. As the test shows, it does revert an earlier fix, but arguably that 
earlier fix was the wrong solution to a reported inconsistency.

The earlier test was specific to a particular condition ... using -link 
and -d to point to the same value. That's arguably worth checking for in 
its own right, but that's a different issue and should have a different 
error message.

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

-- Jon


On 11/21/2017 07:22 AM, Kumar Srinivasan wrote:
> Hello,
>
> Please review this simple fix for [1], webrev at [2].
>
> Thanks
> Kumar
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8180019
> [2] http://cr.openjdk.java.net/~ksrini/8180019/webrev.00/


From jonathan.gibbons at oracle.com  Wed Nov 22 00:25:28 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Tue, 21 Nov 2017 16:25:28 -0800
Subject: RFR:8185985:Html files in doc-files directories should be wrapped
In-Reply-To: <5A04E00E.4040705@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A03AB76.8000708@oracle.com> <5A04E00E.4040705@oracle.com>
Message-ID: <5A14C3F8.1020305@oracle.com>

DocletElement:84

   83      * Returns the anchoring package element, in the case of a
   84      * module element, this could be an unnamed package.

Change to:     this is the module's unnamed package

DocFilesHandlerImpl

  199         sb.trimToSize();
  200         return docletWriter.getWindowTitle(sb.toString().trim());

No need for line 199; remove it

DocFilesHandler.java

   39     void copyDocFiles() throws DocletException ;

Space before ';'


It would be nice if the MODULE and PACKAGE links were active.

-- Jon


On 11/09/2017 03:09 PM, Kumar Srinivasan wrote:
> Hi Jon,
>
> [changed subj line to reflect the current review]
> Full webrev:
> http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/
>
> Delta webrev:
> http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/webrev.delta/
>
>> Here's comments on the code (not looked at the tests yet).
>>
>> On 11/06/2017 06:04 PM, Kumar Srinivasan wrote:
>>>
>>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/ 
>>
>> HtmlDocletWriter: line 451-493
>> I accept you have put the new code after the existing like-named method,
>> but we're still trying to de-clutter classes like HtmlDocletWriter.
>> The new method seems like a combination of two methods ...
>> one is new functionality to extract the TITLE from an HTML document,
>> and the other is a simple call onto the existing getWindowTitle.
>>
>> I'm also not sure that the filename is a good default. But that being 
>> said,
>> TITLE is not an optional element in a HEAD section, and should always be
>> provided, and so a non-empty default may never normally be required.
>
>  I have changed it to  use an empty string.
>
>
>>
>>
>> HtmlDocletWriter: line 2495,2496
>> Suggest increasing indent of parameter list
>
> Done
>
>>
>> WriterFactoryImpl: 244
>> You're in a class called "WriterFactoryImpl" and the method is named 
>> "getDocFilesWriter"
>> and yet it returns an object whose type is DocFilesHandler, instead 
>> of DocFilesWriter.
>> Just sayin'....
>
> Fixed
>
>>
>> BaseConfiguration:378
>> Were you going to move this assignment later in the execution?
>
> Done
>
>
>>
>> CommentUtils:183
>> When is the returned type not a PackageElement?
>> Why is the return type of the method not PackageElement?
>> If it can be something else, like a module element, should there be a 
>> check here?
>
> Fixed
>>
>> CommentUtil:219-221
>> The comment requires some mental gymnastics to guess any possible 
>> meaning.
>> If you know what it means, can you rewrite it please?
> Fixed
>
>>
>> OverviewElement
>> We definitely talked about removing any direct dependence on and 
>> storage of
>> BaseConfiguration.
>
> Fixed
>
>>
>> WriterFactory
>> See comments for WriterFactoryImpl re: naming.
>>
>> AnnotationTypeBuilder:31
>> ClassBuilder:31
>> ModuleSummaryBuilder:30
>> PackageSummaryBuilder:34
>> Illegal import. builders cannot depend on types in format-specific 
>> packages
>> (i.e. formats.html)  There needs to be an interface in the toolkit 
>> world, and
>> an impl of the interface in the formats.html world, the same as is 
>> done for
>> other Writer/WriterImpl pairs.
>
> Done
>
>>
>> ModuleSummaryBuilder:120
>> You're very close to being able to support this. The PackageElement for
>> the DocletElement would be the unnamed package for the module.
>
> It all seems to work, for modules, however I have disabled it for now, 
> added suitable
> comments.
>
>>
>> DocFile:106
>> Grumble, why do you need this?  In general, the doclet world uses 
>> DocFile objects
>> not FileObjects
>
> FO needed  for DocTrees.
>
>>
>> DocPaths:173-196
>> This class used to be sorted in case-equivalent alpha order. Somehow, 
>> these 'M'
>> fields and methods have ended up between 'P' and 'R'
>
> Fixed.
>
>>
>> StandardDocFileFactory
>> Again grumble that this is necessary, but I can see where this going
>>
>> Utils
>> Who is now using these copyDirectory methods, since they don't check 
>> for HTML files?
>
> The doclet support files such as resources, jquery etc. Howeve please 
> note the doc-files
> are copied by its own copyDirectory logic.
>
>>
>> DocFilesHandler.java
>> What about .HtMl ... in other words, get the extension and do a 
>> ignore-case check.
>> line 153: in time we'll want more from the <head> than just the 
>> title, so I think
>> getTitle belongs here.  Also, I don't think the title gets properly 
>> propagated to
>> the TITLE in the generated file.
>
> moved it here and converted the file extension check as suggested. And 
> it seems
> to be propagated to the output, there are tests to check this.
>
>>
>> DocFileElement:64
>> You want the unnamed package for the specific module (each module has 
>> its own unnamed package.)
>
> added a comment for future use.
>
>>
>> DocletElement:83,84
>> You can't put types in the unnamed package of a named module, but 
>> javac (Symbol, etc)
>> does understand the concept, and so it is reasonable (in the API) to 
>> get the unnamed package
>> for a named module. You might need a workaround to get it, though.
>
> Fixed comment
>
> Thanks
> Kumar
>
>>
>>
>> -- Jon
>


From kumar.x.srinivasan at oracle.com  Wed Nov 22 19:40:55 2017
From: kumar.x.srinivasan at oracle.com (Kumar Srinivasan)
Date: Wed, 22 Nov 2017 11:40:55 -0800
Subject: RFR:8185985:Html files in doc-files directories should be wrapped
In-Reply-To: <5A14C3F8.1020305@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A03AB76.8000708@oracle.com> <5A04E00E.4040705@oracle.com>
 <5A14C3F8.1020305@oracle.com>
Message-ID: <5A15D2C7.3090309@oracle.com>

Jon,

> DocletElement:84
>
>   83      * Returns the anchoring package element, in the case of a
>   84      * module element, this could be an unnamed package.
>
> Change to:     this is the module's unnamed package

Fixed

> DocFilesHandlerImpl
>
>  199         sb.trimToSize();
>  200         return docletWriter.getWindowTitle(sb.toString().trim());
>
> No need for line 199; remove it

Fixed

>
> DocFilesHandler.java
>
>   39     void copyDocFiles() throws DocletException ;
>
> Space before ';'

Fixed

> It would be nice if the MODULE and PACKAGE links were active.

Done and thanks for the override tip!.

Also added more tests for single and multi modules, the latter the cause 
behind
links not appearing.

The corrected doc-file:
http://cr.openjdk.java.net/~ksrini/8185985/api-docs/api/java/util/doc-files/coll-index.html

Delta webrev:
http://cr.openjdk.java.net/~ksrini/8185985/webrev.02/webrev.delta/


Thanks
Kumar




>
> -- Jon
>
>
> On 11/09/2017 03:09 PM, Kumar Srinivasan wrote:
>> Hi Jon,
>>
>> [changed subj line to reflect the current review]
>> Full webrev:
>> http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/
>>
>> Delta webrev:
>> http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/webrev.delta/
>>
>>> Here's comments on the code (not looked at the tests yet).
>>>
>>> On 11/06/2017 06:04 PM, Kumar Srinivasan wrote:
>>>>
>>>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>>>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/ 
>>>
>>> HtmlDocletWriter: line 451-493
>>> I accept you have put the new code after the existing like-named 
>>> method,
>>> but we're still trying to de-clutter classes like HtmlDocletWriter.
>>> The new method seems like a combination of two methods ...
>>> one is new functionality to extract the TITLE from an HTML document,
>>> and the other is a simple call onto the existing getWindowTitle.
>>>
>>> I'm also not sure that the filename is a good default. But that 
>>> being said,
>>> TITLE is not an optional element in a HEAD section, and should 
>>> always be
>>> provided, and so a non-empty default may never normally be required.
>>
>>  I have changed it to  use an empty string.
>>
>>
>>>
>>>
>>> HtmlDocletWriter: line 2495,2496
>>> Suggest increasing indent of parameter list
>>
>> Done
>>
>>>
>>> WriterFactoryImpl: 244
>>> You're in a class called "WriterFactoryImpl" and the method is named 
>>> "getDocFilesWriter"
>>> and yet it returns an object whose type is DocFilesHandler, instead 
>>> of DocFilesWriter.
>>> Just sayin'....
>>
>> Fixed
>>
>>>
>>> BaseConfiguration:378
>>> Were you going to move this assignment later in the execution?
>>
>> Done
>>
>>
>>>
>>> CommentUtils:183
>>> When is the returned type not a PackageElement?
>>> Why is the return type of the method not PackageElement?
>>> If it can be something else, like a module element, should there be 
>>> a check here?
>>
>> Fixed
>>>
>>> CommentUtil:219-221
>>> The comment requires some mental gymnastics to guess any possible 
>>> meaning.
>>> If you know what it means, can you rewrite it please?
>> Fixed
>>
>>>
>>> OverviewElement
>>> We definitely talked about removing any direct dependence on and 
>>> storage of
>>> BaseConfiguration.
>>
>> Fixed
>>
>>>
>>> WriterFactory
>>> See comments for WriterFactoryImpl re: naming.
>>>
>>> AnnotationTypeBuilder:31
>>> ClassBuilder:31
>>> ModuleSummaryBuilder:30
>>> PackageSummaryBuilder:34
>>> Illegal import. builders cannot depend on types in format-specific 
>>> packages
>>> (i.e. formats.html)  There needs to be an interface in the toolkit 
>>> world, and
>>> an impl of the interface in the formats.html world, the same as is 
>>> done for
>>> other Writer/WriterImpl pairs.
>>
>> Done
>>
>>>
>>> ModuleSummaryBuilder:120
>>> You're very close to being able to support this. The PackageElement for
>>> the DocletElement would be the unnamed package for the module.
>>
>> It all seems to work, for modules, however I have disabled it for 
>> now, added suitable
>> comments.
>>
>>>
>>> DocFile:106
>>> Grumble, why do you need this?  In general, the doclet world uses 
>>> DocFile objects
>>> not FileObjects
>>
>> FO needed  for DocTrees.
>>
>>>
>>> DocPaths:173-196
>>> This class used to be sorted in case-equivalent alpha order. 
>>> Somehow, these 'M'
>>> fields and methods have ended up between 'P' and 'R'
>>
>> Fixed.
>>
>>>
>>> StandardDocFileFactory
>>> Again grumble that this is necessary, but I can see where this going
>>>
>>> Utils
>>> Who is now using these copyDirectory methods, since they don't check 
>>> for HTML files?
>>
>> The doclet support files such as resources, jquery etc. Howeve please 
>> note the doc-files
>> are copied by its own copyDirectory logic.
>>
>>>
>>> DocFilesHandler.java
>>> What about .HtMl ... in other words, get the extension and do a 
>>> ignore-case check.
>>> line 153: in time we'll want more from the <head> than just the 
>>> title, so I think
>>> getTitle belongs here.  Also, I don't think the title gets properly 
>>> propagated to
>>> the TITLE in the generated file.
>>
>> moved it here and converted the file extension check as suggested. 
>> And it seems
>> to be propagated to the output, there are tests to check this.
>>
>>>
>>> DocFileElement:64
>>> You want the unnamed package for the specific module (each module 
>>> has its own unnamed package.)
>>
>> added a comment for future use.
>>
>>>
>>> DocletElement:83,84
>>> You can't put types in the unnamed package of a named module, but 
>>> javac (Symbol, etc)
>>> does understand the concept, and so it is reasonable (in the API) to 
>>> get the unnamed package
>>> for a named module. You might need a workaround to get it, though.
>>
>> Fixed comment
>>
>> Thanks
>> Kumar
>>
>>>
>>>
>>> -- Jon
>>
>


From jonathan.gibbons at oracle.com  Wed Nov 22 21:19:03 2017
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Wed, 22 Nov 2017 13:19:03 -0800
Subject: RFR:8185985:Html files in doc-files directories should be wrapped
In-Reply-To: <5A15D2C7.3090309@oracle.com>
References: <5A0114A1.7080909@oracle.com> <5A0115E6.3070509@oracle.com>
 <5A03AB76.8000708@oracle.com> <5A04E00E.4040705@oracle.com>
 <5A14C3F8.1020305@oracle.com> <5A15D2C7.3090309@oracle.com>
Message-ID: <5A15E9C7.3020402@oracle.com>

OK, but I also note there is a minor visual regression in the doc-file 
pages.

Previously, the pages relied on the default style, which gave some left 
margin.  Now the pages are picking up elements of the doclet style, 
which has no left margin. This needs to be fixed at some point, perhaps 
as part of the overall stylesheet cleanup, and the subgoal within that 
to better separate the styles for user-written content from the styles 
for doclet-generated content.

-- Jon

On 11/22/2017 11:40 AM, Kumar Srinivasan wrote:
> Jon,
>
>> DocletElement:84
>>
>>   83      * Returns the anchoring package element, in the case of a
>>   84      * module element, this could be an unnamed package.
>>
>> Change to:     this is the module's unnamed package
>
> Fixed
>
>> DocFilesHandlerImpl
>>
>>  199         sb.trimToSize();
>>  200         return docletWriter.getWindowTitle(sb.toString().trim());
>>
>> No need for line 199; remove it
>
> Fixed
>
>>
>> DocFilesHandler.java
>>
>>   39     void copyDocFiles() throws DocletException ;
>>
>> Space before ';'
>
> Fixed
>
>> It would be nice if the MODULE and PACKAGE links were active.
>
> Done and thanks for the override tip!.
>
> Also added more tests for single and multi modules, the latter the 
> cause behind
> links not appearing.
>
> The corrected doc-file:
> http://cr.openjdk.java.net/~ksrini/8185985/api-docs/api/java/util/doc-files/coll-index.html 
>
>
> Delta webrev:
> http://cr.openjdk.java.net/~ksrini/8185985/webrev.02/webrev.delta/
>
>
> Thanks
> Kumar
>
>
>
>
>>
>> -- Jon
>>
>>
>> On 11/09/2017 03:09 PM, Kumar Srinivasan wrote:
>>> Hi Jon,
>>>
>>> [changed subj line to reflect the current review]
>>> Full webrev:
>>> http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/
>>>
>>> Delta webrev:
>>> http://cr.openjdk.java.net/~ksrini/8185985/webrev.01/webrev.delta/
>>>
>>>> Here's comments on the code (not looked at the tests yet).
>>>>
>>>> On 11/06/2017 06:04 PM, Kumar Srinivasan wrote:
>>>>>
>>>>> [3] https://bugs.openjdk.java.net/browse/JDK-8185985
>>>>> [4] http://cr.openjdk.java.net/~ksrini/8185985/webrev.00/ 
>>>>
>>>> HtmlDocletWriter: line 451-493
>>>> I accept you have put the new code after the existing like-named 
>>>> method,
>>>> but we're still trying to de-clutter classes like HtmlDocletWriter.
>>>> The new method seems like a combination of two methods ...
>>>> one is new functionality to extract the TITLE from an HTML document,
>>>> and the other is a simple call onto the existing getWindowTitle.
>>>>
>>>> I'm also not sure that the filename is a good default. But that 
>>>> being said,
>>>> TITLE is not an optional element in a HEAD section, and should 
>>>> always be
>>>> provided, and so a non-empty default may never normally be required.
>>>
>>>  I have changed it to  use an empty string.
>>>
>>>
>>>>
>>>>
>>>> HtmlDocletWriter: line 2495,2496
>>>> Suggest increasing indent of parameter list
>>>
>>> Done
>>>
>>>>
>>>> WriterFactoryImpl: 244
>>>> You're in a class called "WriterFactoryImpl" and the method is 
>>>> named "getDocFilesWriter"
>>>> and yet it returns an object whose type is DocFilesHandler, instead 
>>>> of DocFilesWriter.
>>>> Just sayin'....
>>>
>>> Fixed
>>>
>>>>
>>>> BaseConfiguration:378
>>>> Were you going to move this assignment later in the execution?
>>>
>>> Done
>>>
>>>
>>>>
>>>> CommentUtils:183
>>>> When is the returned type not a PackageElement?
>>>> Why is the return type of the method not PackageElement?
>>>> If it can be something else, like a module element, should there be 
>>>> a check here?
>>>
>>> Fixed
>>>>
>>>> CommentUtil:219-221
>>>> The comment requires some mental gymnastics to guess any possible 
>>>> meaning.
>>>> If you know what it means, can you rewrite it please?
>>> Fixed
>>>
>>>>
>>>> OverviewElement
>>>> We definitely talked about removing any direct dependence on and 
>>>> storage of
>>>> BaseConfiguration.
>>>
>>> Fixed
>>>
>>>>
>>>> WriterFactory
>>>> See comments for WriterFactoryImpl re: naming.
>>>>
>>>> AnnotationTypeBuilder:31
>>>> ClassBuilder:31
>>>> ModuleSummaryBuilder:30
>>>> PackageSummaryBuilder:34
>>>> Illegal import. builders cannot depend on types in format-specific 
>>>> packages
>>>> (i.e. formats.html)  There needs to be an interface in the toolkit 
>>>> world, and
>>>> an impl of the interface in the formats.html world, the same as is 
>>>> done for
>>>> other Writer/WriterImpl pairs.
>>>
>>> Done
>>>
>>>>
>>>> ModuleSummaryBuilder:120
>>>> You're very close to being able to support this. The PackageElement 
>>>> for
>>>> the DocletElement would be the unnamed package for the module.
>>>
>>> It all seems to work, for modules, however I have disabled it for 
>>> now, added suitable
>>> comments.
>>>
>>>>
>>>> DocFile:106
>>>> Grumble, why do you need this?  In general, the doclet world uses 
>>>> DocFile objects
>>>> not FileObjects
>>>
>>> FO needed  for DocTrees.
>>>
>>>>
>>>> DocPaths:173-196
>>>> This class used to be sorted in case-equivalent alpha order. 
>>>> Somehow, these 'M'
>>>> fields and methods have ended up between 'P' and 'R'
>>>
>>> Fixed.
>>>
>>>>
>>>> StandardDocFileFactory
>>>> Again grumble that this is necessary, but I can see where this going
>>>>
>>>> Utils
>>>> Who is now using these copyDirectory methods, since they don't 
>>>> check for HTML files?
>>>
>>> The doclet support files such as resources, jquery etc. Howeve 
>>> please note the doc-files
>>> are copied by its own copyDirectory logic.
>>>
>>>>
>>>> DocFilesHandler.java
>>>> What about .HtMl ... in other words, get the extension and do a 
>>>> ignore-case check.
>>>> line 153: in time we'll want more from the <head> than just the 
>>>> title, so I think
>>>> getTitle belongs here.  Also, I don't think the title gets properly 
>>>> propagated to
>>>> the TITLE in the generated file.
>>>
>>> moved it here and converted the file extension check as suggested. 
>>> And it seems
>>> to be propagated to the output, there are tests to check this.
>>>
>>>>
>>>> DocFileElement:64
>>>> You want the unnamed package for the specific module (each module 
>>>> has its own unnamed package.)
>>>
>>> added a comment for future use.
>>>
>>>>
>>>> DocletElement:83,84
>>>> You can't put types in the unnamed package of a named module, but 
>>>> javac (Symbol, etc)
>>>> does understand the concept, and so it is reasonable (in the API) 
>>>> to get the unnamed package
>>>> for a named module. You might need a workaround to get it, though.
>>>
>>> Fixed comment
>>>
>>> Thanks
>>> Kumar
>>>
>>>>
>>>>
>>>> -- Jon
>>>
>>
>