From priya.lakshmi.muthuswamy at oracle.com Fri Jun 1 09:34:28 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Fri, 1 Jun 2018 15:04:28 +0530 Subject: RFR:JDK-8190875:modules not listed in overview/index page Message-ID: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8190875 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ Thanks, Priya From priya.lakshmi.muthuswamy at oracle.com Fri Jun 1 12:54:22 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Fri, 1 Jun 2018 18:24:22 +0530 Subject: RFR:JDK-8199268:docs/api/jdk.javadoc/com/sun/javadoc/package-summary.html contain low contrast text. Message-ID: <50eda6ed-f0d8-229b-8266-911cf120efe2@oracle.com> Hi, Please review a simple fix for https://bugs.openjdk.java.net/browse/JDK-8199268 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199268/webrev.00/ Thanks, Priya From jonathan.gibbons at oracle.com Fri Jun 1 14:12:15 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 1 Jun 2018 07:12:15 -0700 Subject: RFR:JDK-8199268:docs/api/jdk.javadoc/com/sun/javadoc/package-summary.html contain low contrast text. In-Reply-To: <50eda6ed-f0d8-229b-8266-911cf120efe2@oracle.com> References: <50eda6ed-f0d8-229b-8266-911cf120efe2@oracle.com> Message-ID: <91303a22-86c7-1f5a-6c04-9ac0d44fd3ce@oracle.com> OK On 6/1/18 5:54 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Please review a simple fix for > https://bugs.openjdk.java.net/browse/JDK-8199268 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199268/webrev.00/ > > Thanks, > Priya > > From jonathan.gibbons at oracle.com Fri Jun 1 19:58:18 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 01 Jun 2018 12:58:18 -0700 Subject: RFR:JDK-8190875:modules not listed in overview/index page In-Reply-To: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> References: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> Message-ID: <5B11A55A.9040406@oracle.com> On 06/01/2018 02:34 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8190875 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ > > Thanks, > Priya You are using a single shared src directory, and mutating it in the various test cases. This means that the test cases are not independent, and depend on the (unspecified) order of execution of the test cases. You should create a new copy of the "src" directory as a new subdirectory of the "base" directory in each test case. -- Jon From priya.lakshmi.muthuswamy at oracle.com Mon Jun 4 04:07:14 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 4 Jun 2018 09:37:14 +0530 Subject: RFR:JDK-8190875:modules not listed in overview/index page In-Reply-To: <5B11A55A.9040406@oracle.com> References: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> <5B11A55A.9040406@oracle.com> Message-ID: <89eb1996-7b5c-c452-8e6c-47fad36615d5@oracle.com> Hi Jon, I have updated the webrev with the suggestions. webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.01/ Thanks, Priya On 6/2/2018 1:28 AM, Jonathan Gibbons wrote: > > > On 06/01/2018 02:34 AM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the fix for >> https://bugs.openjdk.java.net/browse/JDK-8190875 >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ >> >> Thanks, >> Priya > > You are using a single shared src directory, and mutating it in the > various test cases. > This means that the test cases are not independent, and depend on the > (unspecified) > order of execution of the test cases. > > You should create a new copy of the "src" directory as a new > subdirectory of the "base" > directory in each test case. > > -- Jon From priya.lakshmi.muthuswamy at oracle.com Mon Jun 4 05:39:08 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 4 Jun 2018 11:09:08 +0530 Subject: RFR:8199893:the javadoc tool generates pages with a low constrast Message-ID: <334f18ff-4eaa-f369-7985-d3d7e8ea6571@oracle.com> Hi, Kindly review simple fix for https://bugs.openjdk.java.net/browse/JDK-8199893 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199893/webrev.00/ Thanks, Priya From jonathan.gibbons at oracle.com Mon Jun 4 15:58:49 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 4 Jun 2018 08:58:49 -0700 Subject: Fwd: Re: running javadoc against multiple modules In-Reply-To: <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> References: <5B0D9CE6.2090308@oracle.com> <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com> <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> Message-ID: <94e6cad1-b66c-7c71-ebb9-304857de2729@oracle.com> Rick, I will have to set up a clone of your world, using the attachment you provided last week, to investigate this further. -- Jon On 6/2/18 8:12 AM, Rick Hillegas wrote: > Thanks for that explanation, Jon. You are right, Derby builds one > component at a time, adding previously compiled components onto the > classpaths of later components. > > I'm afraid that I haven't figured out what other options to use > alongside --patch-module: > > # error: module not found: org.test.secondmodule > # error: module not found: org.test.firstmodule > javadoc --module-source-path ./emptyDir \ > ??????? -d build/javadoc \ > ??????? --module org.test.firstmodule,org.test.secondmodule \ > ??????? --patch-module org.test.firstmodule=./java/firstmodule \ > ??????? --patch-module org.test.secondmodule=./java/secondmodule > > Thanks for any further advice you can give, > -Rick > > > On 5/30/18 4:36 PM, Jonathan Gibbons wrote: >> Rick, >> >> Thank you for explaining the context of your questions. >> >> With respect, you are mistaken with respect to javac's behavior, if >> only because it's the same code shared by javac and javadoc, >> >> --module-source-path requires there to be a level in the directory >> hierarchy that is named for the module.? The name is required in >> order to find the source for a module, when resolve a directive like >> "requires moduleName;".? Just as javac requires that classes can be >> looked up in a directory hierarchy that corresponds to the package >> hierarchy, so too does javac and javadoc impose a requirement that >> the source for a module be in a suitably-named directory when using >> the module source path. >> >> It may be that you have not encountered the equivalent situation in >> javac if you have managed to compile your code one module at a time, >> placing the output from previous compilations on the module path. In >> that situation, would would not need to use the --module-source-path >> option, which is necessary when you want to read/analyze/compile the >> source code for several modules at once. >> >> Although I grant that the text in JEP 261 could be clearer, this is >> the relevant text: >>> >>> In large systems the source code for a particular module may be >>> spread across several different directories.In the JDK itself >>> ,/e.g./, the source files for a >>> module may be found in any one of the >>> directories|src//share/classes|,|src///classes|, >>> or|build/gensrc/|, where||is the name of the target >>> operating system. To express this in a module source path while >>> preserving module identities we allow each element of such a path to >>> use braces (|{|and|}|) to enclose commas-separated lists of >>> alternatives and a single asterisk (|*|) to stand for the module >>> name. The module source path for the JDK can then be written as >>> >>> |{src/*/{share,}/classes,build/gensrc/*}| >> >> The reference to '*' is the presence of the module name. >> >> I understand the difficulty this restriction may cause some existing >> older software systems. At some level, I'm impressed you have gotten >> as far as you have without running into this restriction before! >> >> All that having been said, there may be a way forward for you. The >> following may seen a bit cumbersome, but it may allow you to run >> javadoc (or javac) without renaming your source directories.? You can >> do this with a combination of --module-source-path and >> --patch-module, as follows: >> >> 1. Point --module-source-path at an empty directory.? The presence of >> the option is required so that the tool is put into "multi-module mode". >> >> 2. For each of the modules you want to process, use an option like this: >> ??? ??? --patch-module = >> >> ??? The is as it would appear in the module >> declaration;? the is a "source path", >> meaning one or more directories separated by the system path >> separator character (either ':' on Unix-like systems, or ';' on >> Windows.)? As a source path, the directories on the path must all be >> directories at the root of a package hierarchy. >> >> ??? So, for example, for one of your modules, the option would be >> >> ??? ??? --patch-module org.test.firstmodule=./java/firstmodule >> >> ??? And you would repeat that as needed for all the other modules you >> want to pass to javadoc >> >> -- Jon >> >> >> On 5/30/18 4:08 PM, Rick Hillegas wrote: >>> Thanks for that explanation, Jon. >>> >>> I'm asking these questions because I'm near the end of modularizing >>> a very old body of software, Apache Derby. I have successfully >>> created module descriptors for all of the Derby components and I >>> have not had to rename any directories. The naming limitation you >>> describe does not constrain javac. Javac does not impose any >>> restrictions on the names of the root directories of components. >>> >>> I do not see this limitation in JEP 261. Stephen Colbourne seems to >>> recommend the practice which you are advocating >>> (http://blog.joda.org/2017/04/java-se-9-jpms-module-naming.html) but >>> he merely states a strong recommendation. My sense is that it is a >>> best practice for greenfield projects. It is clearly a big hurdle >>> for legacy projects to surmount. >>> >>> Thanks for this clarification, >>> -Rick >>> >>> On 5/30/18 7:34 AM, Jonathan Gibbons wrote: >>>> >>>> Sorry, I missed that detail when looking at your example yesterday. >>>> >>>> The error message says it all. >>>> >>>> When you're working with multiple modules on the module source >>>> path, each module must be in a directory that is named after the >>>> module it contains. Think of it as the module-level equivalent of >>>> the requirement that classes in a package hierarchy should be >>>> organized in a directory hierarchy that mirrors the package hierarchy. >>>> >>>> If your modules are named org.test.firstmodule and >>>> org.test.secondmodule, your ./java directory should contain direct >>>> subdirectories with those exact names. Within each directory, you >>>> can place the package hierarchy for the content of that module.? In >>>> simple cases, you can place the package hierarchy directly in the >>>> module directory, although with a more complex value for the >>>> --module-source-path option, you can set up a system with >>>> intervening directories between the module directory and the root >>>> of the package hierarchy. >>>> >>>> The module paths are described in JEP 261. >>>> http://openjdk.java.net/jeps/261 Although that JEP does not call >>>> out javadoc, the description for javac essentially applies to >>>> javadoc as well. >>>> >>>> -- Jon >>>> >>>> >>>> On 5/29/18 4:02 PM, Rick Hillegas wrote: >>>>> >>>>> Thanks, Jon. That moved the problem forward. Now I am getting an >>>>> error because a module's name does not match the root directory of >>>>> its source code. The following command... >>>>> >>>>> ? javadoc --module-source-path ./java \ >>>>> ???? -d build/javadoc \ >>>>> ???? --module firstmodule,secondmodule >>>>> >>>>> >>>>> ...raises the following errors: >>>>> >>>>> ? ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule >>>>> does not match expected name secondmodule >>>>> ? module org.test.secondmodule >>>>> ? ^ >>>>> ? ./java/secondmodule/module-info.java:5: error: module not found: >>>>> org.test.firstmodule >>>>> ??? requires org.test.firstmodule; >>>>> ???????????????????? ^ >>>>> ? error: cannot access module-info >>>>> ??? cannot resolve modules >>>>> ? 3 errors >>>>> >>>>> >>>>> I get a different error when I change the names of the modules >>>>> which I hand to the --module switch. The following command... >>>>> >>>>> ? javadoc --module-source-path ./java \ >>>>> ??? -d build/javadoc \ >>>>> ??? --module org.test.firstmodule,org.test.secondmodule >>>>> >>>>> >>>>> ...raises the following error... >>>>> >>>>> ? javadoc: error - module org.test.firstmodule not found. >>>>> >>>>> >>>>> I have attached a tarball of my project. >>>>> >>>>> Thanks for any advice you can give me, >>>>> -Rick >>>>> >>>>> >>>>> >>>>> -------- Forwarded Message -------- >>>>> Subject: Re: running javadoc against multiple modules >>>>> Date: Tue, 29 May 2018 11:33:10 -0700 >>>>> From: Jonathan Gibbons >>>>> To: javadoc-dev at openjdk.java.net >>>>> >>>>> >>>>> >>>>> Rick, >>>>> >>>>> Set --module-sourcepath to the directory containing the modules. >>>>> >>>>> Something like this should work for you: >>>>> >>>>> javadoc --module-source-path ./java -d build/javadoc --module >>>>> firstmodule,secondmodule >>>>> >>>>> -- Jon >>>>> >>>>> On 05/20/2018 04:45 PM, Rick Hillegas wrote: >>>>> > I hope that someone can point me at the right documentation for how to >>>>> > create javadoc on a multi-module project. My naive googling does not >>>>> > find any pertinent examples for how to do this from the command line >>>>> > via the javadoc tool. I have looked through the Java 9 tools documents >>>>> > titled "Javadoc Guide" and "Tools Reference" but I have not been able >>>>> > to puzzle out which combination of options will produce a single, >>>>> > unified set of javadoc for multiple modules. This is my first attempt >>>>> > to document a multi-module project, so, no doubt, I am missing >>>>> > something simple but crucial. >>>>> > >>>>> > I am using "Java(TM) SE Runtime Environment (build 9+181)". My source >>>>> > tree looks like this: >>>>> > >>>>> > ./java >>>>> > ./java/firstmodule >>>>> > ./java/firstmodule/firstpackage >>>>> > ./java/firstmodule/firstpackage/FirstClass.java >>>>> > ./java/firstmodule/module-info.java >>>>> > ./java/secondmodule >>>>> > ./java/secondmodule/module-info.java >>>>> > ./java/secondmodule/secondpackage >>>>> > ./java/secondmodule/secondpackage/SecondClass.java >>>>> > >>>>> > >>>>> > The module descriptors look like the following... >>>>> > >>>>> > module org.test.firstmodule >>>>> > >>>>> > { >>>>> > requires java.base; >>>>> > exports firstpackage; >>>>> > } >>>>> > >>>>> > >>>>> > ...and... >>>>> > >>>>> > module org.test.secondmodule >>>>> > >>>>> > { >>>>> > requires java.base; >>>>> > requires org.test.firstmodule; >>>>> > exports secondpackage; >>>>> > } >>>>> > >>>>> > >>>>> > I believe that I have written valid modules, because the following >>>>> > command does what I expect it to do: >>>>> > >>>>> > java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \ >>>>> > -m org.test.secondmodule/secondpackage.SecondClass >>>>> > >>>>> > >>>>> > That is, the java command likes my modules well enough. But javadoc >>>>> > baffles me. >>>>> > >>>>> > The following command... >>>>> > >>>>> > javadoc -sourcepath ./java/firstmodule:./java/secondmodule \ >>>>> > -d build/javadoc \ >>>>> > firstpackage secondpackage >>>>> > >>>>> > >>>>> > ...runs without any errors or warnings. However, it produces odd results: >>>>> > >>>>> > 1) The top level index.html page lists only one module: >>>>> > org.test.firstmodule. I expected to see both modules on the landing page. >>>>> > >>>>> > 2) In addition, SecondClass.html reports that SecondClass lives in the >>>>> > org.test.firstmodule module. I expected that the class would report >>>>> > its home as org.test.secondmodule. >>>>> > >>>>> > The following command... >>>>> > >>>>> > javadoc --module-source-path ./java/firstmodule:./java/secondmodule \ >>>>> > -d build/javadoc \ >>>>> > firstpackage secondpackage >>>>> > >>>>> > >>>>> > ...raises the following error... >>>>> > >>>>> > javadoc: error - No source files for package firstpackage >>>>> > >>>>> > >>>>> > And this command... >>>>> > >>>>> > javadoc --module-source-path ./java/firstmodule:./java/secondmodule \ >>>>> > --module org.test.firstmodule,org.test.secondmodule \ >>>>> > -d build/javadoc \ >>>>> > firstpackage secondpackage >>>>> > >>>>> > >>>>> > ...objects that... >>>>> > >>>>> > javadoc: error - module org.test.firstmodule not found. >>>>> > >>>>> > >>>>> > Clearly, I've wandered off into the tall weeds. I would appreciate >>>>> > your advice and, if possible, a pointer to a primer on this topic. >>>>> > >>>>> > Thanks, >>>>> > -Rick >>>>> > >>>>> >>>>> >>>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: From rick.hillegas at gmail.com Sat Jun 2 15:12:35 2018 From: rick.hillegas at gmail.com (Rick Hillegas) Date: Sat, 2 Jun 2018 08:12:35 -0700 Subject: Fwd: Re: running javadoc against multiple modules In-Reply-To: References: <5B0D9CE6.2090308@oracle.com> <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com> Message-ID: <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> Thanks for that explanation, Jon. You are right, Derby builds one component at a time, adding previously compiled components onto the classpaths of later components. I'm afraid that I haven't figured out what other options to use alongside --patch-module: # error: module not found: org.test.secondmodule # error: module not found: org.test.firstmodule javadoc --module-source-path ./emptyDir \ ??????? -d build/javadoc \ ??????? --module org.test.firstmodule,org.test.secondmodule \ ??????? --patch-module org.test.firstmodule=./java/firstmodule \ ??????? --patch-module org.test.secondmodule=./java/secondmodule Thanks for any further advice you can give, -Rick On 5/30/18 4:36 PM, Jonathan Gibbons wrote: > Rick, > > Thank you for explaining the context of your questions. > > With respect, you are mistaken with respect to javac's behavior, if > only because it's the same code shared by javac and javadoc, > > --module-source-path requires there to be a level in the directory > hierarchy that is named for the module.? The name is required in order > to find the source for a module, when resolve a directive like > "requires moduleName;".? Just as javac requires that classes can be > looked up in a directory hierarchy that corresponds to the package > hierarchy, so too does javac and javadoc impose a requirement that the > source for a module be in a suitably-named directory when using the > module source path. > > It may be that you have not encountered the equivalent situation in > javac if you have managed to compile your code one module at a time, > placing the output from previous compilations on the module path. In > that situation, would would not need to use the --module-source-path > option, which is necessary when you want to read/analyze/compile the > source code for several modules at once. > > Although I grant that the text in JEP 261 could be clearer, this is > the relevant text: >> >> In large systems the source code for a particular module may be >> spread across several different directories.In the JDK itself >> ,/e.g./, the source files for a >> module may be found in any one of the >> directories|src//share/classes|,|src///classes|, >> or|build/gensrc/|, where||is the name of the target >> operating system. To express this in a module source path while >> preserving module identities we allow each element of such a path to >> use braces (|{|and|}|) to enclose commas-separated lists of >> alternatives and a single asterisk (|*|) to stand for the module >> name. The module source path for the JDK can then be written as >> >> |{src/*/{share,}/classes,build/gensrc/*}| > > The reference to '*' is the presence of the module name. > > I understand the difficulty this restriction may cause some existing > older software systems. At some level, I'm impressed you have gotten > as far as you have without running into this restriction before! > > All that having been said, there may be a way forward for you. The > following may seen a bit cumbersome, but it may allow you to run > javadoc (or javac) without renaming your source directories. You can > do this with a combination of --module-source-path and --patch-module, > as follows: > > 1. Point --module-source-path at an empty directory.? The presence of > the option is required so that the tool is put into "multi-module mode". > > 2. For each of the modules you want to process, use an option like this: > ??? ??? --patch-module = > > ??? The is as it would appear in the module > declaration;? the is a "source path", meaning > one or more directories separated by the system path separator > character (either ':' on Unix-like systems, or ';' on Windows.)? As a > source path, the directories on the path must all be directories at > the root of a package hierarchy. > > ??? So, for example, for one of your modules, the option would be > > ??? ??? --patch-module org.test.firstmodule=./java/firstmodule > > ??? And you would repeat that as needed for all the other modules you > want to pass to javadoc > > -- Jon > > > On 5/30/18 4:08 PM, Rick Hillegas wrote: >> Thanks for that explanation, Jon. >> >> I'm asking these questions because I'm near the end of modularizing a >> very old body of software, Apache Derby. I have successfully created >> module descriptors for all of the Derby components and I have not had >> to rename any directories. The naming limitation you describe does >> not constrain javac. Javac does not impose any restrictions on the >> names of the root directories of components. >> >> I do not see this limitation in JEP 261. Stephen Colbourne seems to >> recommend the practice which you are advocating >> (http://blog.joda.org/2017/04/java-se-9-jpms-module-naming.html) but >> he merely states a strong recommendation. My sense is that it is a >> best practice for greenfield projects. It is clearly a big hurdle for >> legacy projects to surmount. >> >> Thanks for this clarification, >> -Rick >> >> On 5/30/18 7:34 AM, Jonathan Gibbons wrote: >>> >>> Sorry, I missed that detail when looking at your example yesterday. >>> >>> The error message says it all. >>> >>> When you're working with multiple modules on the module source path, >>> each module must be in a directory that is named after the module it >>> contains. Think of it as the module-level equivalent of the >>> requirement that classes in a package hierarchy should be organized >>> in a directory hierarchy that mirrors the package hierarchy. >>> >>> If your modules are named org.test.firstmodule and >>> org.test.secondmodule, your ./java directory should contain direct >>> subdirectories with those exact names.? Within each directory, you >>> can place the package hierarchy for the content of that module.? In >>> simple cases, you can place the package hierarchy directly in the >>> module directory, although with a more complex value for the >>> --module-source-path option, you can set up a system with >>> intervening directories between the module directory and the root of >>> the package hierarchy. >>> >>> The module paths are described in JEP 261. >>> http://openjdk.java.net/jeps/261 Although that JEP does not call out >>> javadoc, the description for javac essentially applies to javadoc as >>> well. >>> >>> -- Jon >>> >>> >>> On 5/29/18 4:02 PM, Rick Hillegas wrote: >>>> >>>> Thanks, Jon. That moved the problem forward. Now I am getting an >>>> error because a module's name does not match the root directory of >>>> its source code. The following command... >>>> >>>> ? javadoc --module-source-path ./java \ >>>> ???? -d build/javadoc \ >>>> ???? --module firstmodule,secondmodule >>>> >>>> >>>> ...raises the following errors: >>>> >>>> ? ./java/secondmodule/module-info.java:1: error: module name org.test.secondmodule >>>> does not match expected name secondmodule >>>> ? module org.test.secondmodule >>>> ? ^ >>>> ? ./java/secondmodule/module-info.java:5: error: module not found: >>>> org.test.firstmodule >>>> ??? requires org.test.firstmodule; >>>> ???????????????????? ^ >>>> ? error: cannot access module-info >>>> ??? cannot resolve modules >>>> ? 3 errors >>>> >>>> >>>> I get a different error when I change the names of the modules >>>> which I hand to the --module switch. The following command... >>>> >>>> ? javadoc --module-source-path ./java \ >>>> ??? -d build/javadoc \ >>>> ??? --module org.test.firstmodule,org.test.secondmodule >>>> >>>> >>>> ...raises the following error... >>>> >>>> ? javadoc: error - module org.test.firstmodule not found. >>>> >>>> >>>> I have attached a tarball of my project. >>>> >>>> Thanks for any advice you can give me, >>>> -Rick >>>> >>>> >>>> >>>> -------- Forwarded Message -------- >>>> Subject: Re: running javadoc against multiple modules >>>> Date: Tue, 29 May 2018 11:33:10 -0700 >>>> From: Jonathan Gibbons >>>> To: javadoc-dev at openjdk.java.net >>>> >>>> >>>> >>>> Rick, >>>> >>>> Set --module-sourcepath to the directory containing the modules. >>>> >>>> Something like this should work for you: >>>> >>>> javadoc --module-source-path ./java -d build/javadoc --module >>>> firstmodule,secondmodule >>>> >>>> -- Jon >>>> >>>> On 05/20/2018 04:45 PM, Rick Hillegas wrote: >>>> > I hope that someone can point me at the right documentation for how to >>>> > create javadoc on a multi-module project. My naive googling does not >>>> > find any pertinent examples for how to do this from the command line >>>> > via the javadoc tool. I have looked through the Java 9 tools documents >>>> > titled "Javadoc Guide" and "Tools Reference" but I have not been able >>>> > to puzzle out which combination of options will produce a single, >>>> > unified set of javadoc for multiple modules. This is my first attempt >>>> > to document a multi-module project, so, no doubt, I am missing >>>> > something simple but crucial. >>>> > >>>> > I am using "Java(TM) SE Runtime Environment (build 9+181)". My source >>>> > tree looks like this: >>>> > >>>> > ./java >>>> > ./java/firstmodule >>>> > ./java/firstmodule/firstpackage >>>> > ./java/firstmodule/firstpackage/FirstClass.java >>>> > ./java/firstmodule/module-info.java >>>> > ./java/secondmodule >>>> > ./java/secondmodule/module-info.java >>>> > ./java/secondmodule/secondpackage >>>> > ./java/secondmodule/secondpackage/SecondClass.java >>>> > >>>> > >>>> > The module descriptors look like the following... >>>> > >>>> > module org.test.firstmodule >>>> > >>>> > { >>>> > requires java.base; >>>> > exports firstpackage; >>>> > } >>>> > >>>> > >>>> > ...and... >>>> > >>>> > module org.test.secondmodule >>>> > >>>> > { >>>> > requires java.base; >>>> > requires org.test.firstmodule; >>>> > exports secondpackage; >>>> > } >>>> > >>>> > >>>> > I believe that I have written valid modules, because the following >>>> > command does what I expect it to do: >>>> > >>>> > java -p build/jars/firstmodule.jar:build/jars/secondmodule.jar \ >>>> > -m org.test.secondmodule/secondpackage.SecondClass >>>> > >>>> > >>>> > That is, the java command likes my modules well enough. But javadoc >>>> > baffles me. >>>> > >>>> > The following command... >>>> > >>>> > javadoc -sourcepath ./java/firstmodule:./java/secondmodule \ >>>> > -d build/javadoc \ >>>> > firstpackage secondpackage >>>> > >>>> > >>>> > ...runs without any errors or warnings. However, it produces odd results: >>>> > >>>> > 1) The top level index.html page lists only one module: >>>> > org.test.firstmodule. I expected to see both modules on the landing page. >>>> > >>>> > 2) In addition, SecondClass.html reports that SecondClass lives in the >>>> > org.test.firstmodule module. I expected that the class would report >>>> > its home as org.test.secondmodule. >>>> > >>>> > The following command... >>>> > >>>> > javadoc --module-source-path ./java/firstmodule:./java/secondmodule \ >>>> > -d build/javadoc \ >>>> > firstpackage secondpackage >>>> > >>>> > >>>> > ...raises the following error... >>>> > >>>> > javadoc: error - No source files for package firstpackage >>>> > >>>> > >>>> > And this command... >>>> > >>>> > javadoc --module-source-path ./java/firstmodule:./java/secondmodule \ >>>> > --module org.test.firstmodule,org.test.secondmodule \ >>>> > -d build/javadoc \ >>>> > firstpackage secondpackage >>>> > >>>> > >>>> > ...objects that... >>>> > >>>> > javadoc: error - module org.test.firstmodule not found. >>>> > >>>> > >>>> > Clearly, I've wandered off into the tall weeds. I would appreciate >>>> > your advice and, if possible, a pointer to a primer on this topic. >>>> > >>>> > Thanks, >>>> > -Rick >>>> > >>>> >>>> >>> >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: From sundararajan.athijegannathan at oracle.com Mon Jun 4 12:33:46 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Mon, 04 Jun 2018 18:03:46 +0530 Subject: RFR 8203780: javadoc should be updated to use jquery 1.12.4 and jszip v3.1.5 Message-ID: <5B1531AA.5050308@oracle.com> Please review fix for https://bugs.openjdk.java.net/browse/JDK-8203780 Webrev: http://cr.openjdk.java.net/~sundar/8203780/webrev.00/ Thanks, -Sundar -------------- next part -------------- An HTML attachment was scrubbed... URL: From jonathan.gibbons at oracle.com Mon Jun 4 21:11:12 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 04 Jun 2018 14:11:12 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames Message-ID: <5B15AAF0.2090404@oracle.com> JDK-8196202 [1] introduced a change to the javadoc tool (and because of that, to the Java SE API documentation) such that frames are not generated by default. This has had a deliberate but somewhat unexpected consequence on the Java SE API docs, of getting "404: Not found" on URLs that explicitly referenced the .../api/overview-summary.html page. Here is what happened: The issue is that previously there were two pages: * index.html (contained the frame definitions) * overview-summary.html (contained the content for the main top-level user-visible page) Now that we are not generating frames by default, we only need one page. The tool is generating the content for the main top-level user-visible page in index.html, and there is no need for overview-summary.html page, which is therefore not generated. This behavior has been the behavior since the javadoc option --no-frames was added a year ago. In other words, the recent change [2] was just to flip the default, not to substantially change the behavior of the --frames and --no-frames options. @@ -197,13 +197,13 @@ */ public boolean createoverview = false; /** * Specifies whether or not frames should be generated. - * Defaults to true; can be set by --frames; can be set to false by --no-frames; last one wins. + * Defaults to false; can be set to true by --frames; can be set to false by --no-frames; last one wins. */ - public boolean frames = true; + public boolean frames = false; /** * This is the HTML version of the generated pages. * The default value is determined later. */ So, what are our options. 0. Do nothing. People, and search engines, will learn to use a URL ending in "api/" or "api/index.html" 1. Back out the change. This is undesirable, because the plan is to eventually eliminate all support for frames, and this change was one step in that sequence. 2. Without backing out the change to the tool, we could reverse the effect of the change in the Java SE API documentation, by specifying the use of the --frames options to generate the Java SE API docs. But like #1, this is undesirable because of the plan to remove support for frames. 3. Generate overview-summary.html instead of index.html. This will break folk that think that api/index.html is the top level file. 4. Generate overview-summary.html instead of index.html, and generate index.html with a redirect to overview-summary.html 5. Leave the current behavior, but add back overview-summary.html as a redirect to index.html. Long term, of the two names, index.html is a better default for the top level page than overview-summary.html. This suggests that the top two choices are option #0 and option #5, with #5 providing some minor short-term relief for folk who expect to see overview-summary.html. -- Jon [1] https://bugs.openjdk.java.net/browse/JDK-8196202 [2] http://cr.openjdk.java.net/~jjg/8196202/webrev.00/ -------------- next part -------------- An HTML attachment was scrubbed... URL: From martinrb at google.com Mon Jun 4 21:17:47 2018 From: martinrb at google.com (Martin Buchholz) Date: Mon, 4 Jun 2018 14:17:47 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames In-Reply-To: <5B15AAF0.2090404@oracle.com> References: <5B15AAF0.2090404@oracle.com> Message-ID: On Mon, Jun 4, 2018 at 2:11 PM, Jonathan Gibbons < jonathan.gibbons at oracle.com> wrote: > JDK-8196202 [1] introduced a change to the javadoc tool (and because of > that, to the Java SE API documentation) such that frames are not generated > by default. > > This has had a deliberate but somewhat unexpected consequence on the Java > SE API docs, of getting "404: Not found" on URLs that explicitly referenced > the .../api/overview-summary.html page. > > Here is what happened: > > The issue is that previously there were two pages: > > - index.html (contained the frame definitions) > - overview-summary.html (contained the content for the main top-level > user-visible page) > > Now that we are not generating frames by default, we only need one page. > The tool is generating the content for the main top-level user-visible page > in index.html, and there is no need for overview-summary.html page, which > is therefore not generated. > > This behavior has been the behavior since the javadoc option --no-frames > was added a year ago. In other words, the recent change [2] was just to > flip the default, not to substantially change the behavior of the --frames > and --no-frames options. > > @@ -197,13 +197,13 @@ > */ > public boolean createoverview = false; > > /** > * Specifies whether or not frames should be generated.- * Defaults to true; can be set by --frames; can be set to false by --no-frames; last one wins.+ * Defaults to false; can be set to true by --frames; can be set to false by --no-frames; last one wins. > */- public boolean frames = true;+ public boolean frames = false; > > /** > * This is the HTML version of the generated pages. > * The default value is determined later. > */ > > > So, what are our options. > > 0. Do nothing. People, and search engines, will learn to use a URL > ending in "api/" or "api/index.html" > > 1. Back out the change. This is undesirable, because the plan is to > eventually eliminate all support for frames, and this change was one step > in that sequence. > > 2. Without backing out the change to the tool, we could reverse the effect > of the change in the Java SE API documentation, by specifying the use of > the --frames options to generate the Java SE API docs. But like #1, this is > undesirable because of the plan to remove support for frames. > > 3. Generate overview-summary.html instead of index.html. This will break > folk that think that api/index.html is the top level file. > > 4. Generate overview-summary.html instead of index.html, and generate > index.html with a redirect to overview-summary.html > > 5. Leave the current behavior, but add back overview-summary.html as a > redirect to index.html. > > > Long term, of the two names, index.html is a better default for the top > level page than overview-summary.html. This suggests that the top two > choices are option #0 and option #5, with #5 providing some minor > short-term relief for folk who expect to see overview-summary.html. > I completely agree with your analysis. The reason I (and presumably many others) hard-coded overview-summary.html into my URLs is that I was trained by the javadoc tool. E.g. if I visit https://docs.oracle.com/javase/10/docs/api/ today it gets "corrected" in the address bar of my browser to https://docs.oracle.com/javase/10/docs/api/overview-summary.html and it's natural to copy-paste or bookmark that URL. So overview-summary.html is a public interface, not an implementation detail (even if that was the original intent). The jjava se javadocs are important enough that I would probably do #5 for 5 years or so, during which time you can train people by "correcting" overview-summary.html back to index.html or naked .../api/ whatever you think should be the "canonical" URL. I don't know much about search engines (!) but maybe there's metadata to tell search engines what the canonical URL is (or maybe simply redirects are interpreted that way). -------------- next part -------------- An HTML attachment was scrubbed... URL: From jonathan.gibbons at oracle.com Mon Jun 4 22:06:45 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 04 Jun 2018 15:06:45 -0700 Subject: RFR 8203780: javadoc should be updated to use jquery 1.12.4 and jszip v3.1.5 In-Reply-To: <5B1531AA.5050308@oracle.com> References: <5B1531AA.5050308@oracle.com> Message-ID: <5B15B7F5.2040009@oracle.com> OK -- Jon On 06/04/2018 05:33 AM, Sundararajan Athijegannathan wrote: > Please review fix for https://bugs.openjdk.java.net/browse/JDK-8203780 > > Webrev: http://cr.openjdk.java.net/~sundar/8203780/webrev.00/ > > > Thanks, > -Sundar -------------- next part -------------- An HTML attachment was scrubbed... URL: From jonathan.gibbons at oracle.com Mon Jun 4 22:09:27 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 04 Jun 2018 15:09:27 -0700 Subject: RFR:8199893:the javadoc tool generates pages with a low constrast In-Reply-To: <334f18ff-4eaa-f369-7985-d3d7e8ea6571@oracle.com> References: <334f18ff-4eaa-f369-7985-d3d7e8ea6571@oracle.com> Message-ID: <5B15B897.7090304@oracle.com> OK On 06/03/2018 10:39 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review simple fix for > https://bugs.openjdk.java.net/browse/JDK-8199893 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8199893/webrev.00/ > > Thanks, > Priya > > From jonathan.gibbons at oracle.com Mon Jun 4 22:21:46 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 04 Jun 2018 15:21:46 -0700 Subject: RFR:JDK-8190875:modules not listed in overview/index page In-Reply-To: <89eb1996-7b5c-c452-8e6c-47fad36615d5@oracle.com> References: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> <5B11A55A.9040406@oracle.com> <89eb1996-7b5c-c452-8e6c-47fad36615d5@oracle.com> Message-ID: <5B15BB7A.2060504@oracle.com> It seems weird to have a hybrid methodology, such that you have an explicit side-file (overview.html) but you generate other (source) files on the fly. If you want to keep overview.html as a separate distinct file, it needs to have a full legal header. Yes, I know it is sorta-silly to have a 22 line legal header for a 6 line file, but that's the general rule/guideline, and is also the reason why these days we prefer to generate those files on the fly. You've already got an instance of ToolBox in each of the test cases, but you only need overview.html in one: testIndexWithOverviewPath I recommend using ToolBox.writeFile to create the overview.html file, so that the test becomes self-contained with no need for the side-file. (Side-files are OK if they start getting big and complicated, but don't ask me for a hard and fast rule of when to use an inline string, and when to use a side file. But generally, if the file is "small", generate the file on the fly.) -- Jon On 06/03/2018 09:07 PM, Priya Lakshmi Muthuswamy wrote: > Hi Jon, > > I have updated the webrev with the suggestions. > > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.01/ > > Thanks, > Priya > > On 6/2/2018 1:28 AM, Jonathan Gibbons wrote: >> >> >> On 06/01/2018 02:34 AM, Priya Lakshmi Muthuswamy wrote: >>> Hi, >>> >>> Kindly review the fix for >>> https://bugs.openjdk.java.net/browse/JDK-8190875 >>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ >>> >>> Thanks, >>> Priya >> >> You are using a single shared src directory, and mutating it in the >> various test cases. >> This means that the test cases are not independent, and depend on the >> (unspecified) >> order of execution of the test cases. >> >> You should create a new copy of the "src" directory as a new >> subdirectory of the "base" >> directory in each test case. >> >> -- Jon > From mark.reinhold at oracle.com Mon Jun 4 22:39:51 2018 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Mon, 04 Jun 2018 15:39:51 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames In-Reply-To: References: <5B15AAF0.2090404@oracle.com> Message-ID: <20180604153951.12815057@eggemoggin.niobe.net> 2018/6/4 14:17:47 -0700, Martin Buchholz : > On Mon, Jun 4, 2018 at 2:11 PM, jonathan.gibbons at oracle.com wrote: >> ... >> >> So, what are our options. >> >> 0. Do nothing. People, and search engines, will learn to use a URL >> ending in "api/" or "api/index.html" >> >> 1. Back out the change. This is undesirable, because the plan is to >> eventually eliminate all support for frames, and this change was one step >> in that sequence. >> >> 2. Without backing out the change to the tool, we could reverse the effect >> of the change in the Java SE API documentation, by specifying the use of >> the --frames options to generate the Java SE API docs. But like #1, this is >> undesirable because of the plan to remove support for frames. >> >> 3. Generate overview-summary.html instead of index.html. This will break >> folk that think that api/index.html is the top level file. >> >> 4. Generate overview-summary.html instead of index.html, and generate >> index.html with a redirect to overview-summary.html >> >> 5. Leave the current behavior, but add back overview-summary.html as a >> redirect to index.html. >> >> Long term, of the two names, index.html is a better default for the top >> level page than overview-summary.html. This suggests that the top two >> choices are option #0 and option #5, with #5 providing some minor >> short-term relief for folk who expect to see overview-summary.html. #5 does seem the best option here. > I completely agree with your analysis. The reason I (and presumably many > others) hard-coded overview-summary.html into my URLs is that I was trained > by the javadoc tool. E.g. if I visit > https://docs.oracle.com/javase/10/docs/api/ today it gets "corrected" in > the address bar of my browser to > https://docs.oracle.com/javase/10/docs/api/overview-summary.html and it's > natural to copy-paste or bookmark that URL. Naturally. (For 10, and I assume earlier releases, that ?correction? is helpfully made by a snippet of Javascript in index.html.) > So overview-summary.html is a > public interface, not an implementation detail (even if that was the > original intent). The jjava se javadocs are important enough that I would > probably do #5 for 5 years or so, during which time you can train people by > "correcting" overview-summary.html back to index.html or naked .../api/ > whatever you think should be the "canonical" URL. I don't know much about > search engines (!) but maybe there's metadata to tell search engines what > the canonical URL is (or maybe simply redirects are interpreted that way). Indeed, there is: https://en.wikipedia.org/wiki/Canonical_link_element . - Mark From jonathan.gibbons at oracle.com Mon Jun 4 22:45:41 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 04 Jun 2018 15:45:41 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames In-Reply-To: <20180604153951.12815057@eggemoggin.niobe.net> References: <5B15AAF0.2090404@oracle.com> <20180604153951.12815057@eggemoggin.niobe.net> Message-ID: <5B15C115.4090302@oracle.com> On 06/04/2018 03:39 PM, mark.reinhold at oracle.com wrote: >> I don't know much about >> >search engines (!) but maybe there's metadata to tell search engines what >> >the canonical URL is (or maybe simply redirects are interpreted that way). > Indeed, there is:https://en.wikipedia.org/wiki/Canonical_link_element . > > - Mark Thanks! -- Jon From martinrb at google.com Mon Jun 4 22:54:34 2018 From: martinrb at google.com (Martin Buchholz) Date: Mon, 4 Jun 2018 15:54:34 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames In-Reply-To: <5B15C115.4090302@oracle.com> References: <5B15AAF0.2090404@oracle.com> <20180604153951.12815057@eggemoggin.niobe.net> <5B15C115.4090302@oracle.com> Message-ID: TIL about Canonical link element and 301 redirects. You get to decide whether to follow the joint advice of Google and Microsoft https://en.wikipedia.org/wiki/HTTP_301#Search_engines On Mon, Jun 4, 2018 at 3:45 PM, Jonathan Gibbons < jonathan.gibbons at oracle.com> wrote: > > > On 06/04/2018 03:39 PM, mark.reinhold at oracle.com wrote: > >> I don't know much about >>> >search engines (!) but maybe there's metadata to tell search engines >>> what >>> >the canonical URL is (or maybe simply redirects are interpreted that >>> way). >>> >> Indeed, there is:https://en.wikipedia.org/wiki/Canonical_link_element . >> >> - Mark >> > > Thanks! > > -- Jon > -------------- next part -------------- An HTML attachment was scrubbed... URL: From jonathan.gibbons at oracle.com Mon Jun 4 23:01:54 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 4 Jun 2018 16:01:54 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames In-Reply-To: References: <5B15AAF0.2090404@oracle.com> <20180604153951.12815057@eggemoggin.niobe.net> <5B15C115.4090302@oracle.com> Message-ID: <7e40ecf0-9cc8-3d98-162f-a7daa2e52c06@oracle.com> The doclet already has code to generate redirect pages;? given the short time available for 11, I would prefer to go with what we have. Also, I'm not sure that we can generate a 301 redirect from within a static web page. -- Jon On 6/4/18 3:54 PM, Martin Buchholz wrote: > TIL about Canonical link element and 301 redirects.? You get to decide > whether to follow the joint advice of Google and Microsoft > https://en.wikipedia.org/wiki/HTTP_301#Search_engines > > On Mon, Jun 4, 2018 at 3:45 PM, Jonathan Gibbons > > wrote: > > > > On 06/04/2018 03:39 PM, mark.reinhold at oracle.com > wrote: > > ? I don't know much about > >search engines (!) but maybe there's metadata to tell > search engines what > >the canonical URL is (or maybe simply redirects are > interpreted that way). > > Indeed, there > is:https://en.wikipedia.org/wiki/Canonical_link_element > . > > - Mark > > > Thanks! > > -- Jon > > -------------- next part -------------- An HTML attachment was scrubbed... URL: From mark.reinhold at oracle.com Mon Jun 4 23:01:18 2018 From: mark.reinhold at oracle.com (mark.reinhold at oracle.com) Date: Mon, 04 Jun 2018 16:01:18 -0700 Subject: Change in generated files for SE API docs, caused by change to not generate frames In-Reply-To: References: <5B15AAF0.2090404@oracle.com> <20180604153951.12815057@eggemoggin.niobe.net> <5B15C115.4090302@oracle.com> Message-ID: <20180604160118.739182752@eggemoggin.niobe.net> 2018/6/4 15:54:34 -0700, martinrb at google.com: > TIL about Canonical link element and 301 redirects. You get to decide > whether to follow the joint advice of Google and Microsoft > https://en.wikipedia.org/wiki/HTTP_301#Search_engines Sure, a 301 would be preferable, but it?s not always easy to arrange, and it?s something you have to express outside of Javadoc?s output. A canonical link at least updates the search engines, over time, to go to the right place regardless of how the page is served. If you own the server then by all means arrange for the equivalent 301 (we?ll try to do that on docs.oracle.com). If you put a 301 in place then the canonical link won?t interfere with it. - Mark From sundararajan.athijegannathan at oracle.com Tue Jun 5 06:23:53 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Tue, 05 Jun 2018 11:53:53 +0530 Subject: RFR 8204321: javadoc tests fail after JDK-8203780 Message-ID: <5B162C79.5000404@oracle.com> Please review. Bug: https://bugs.openjdk.java.net/browse/JDK-8204321 Webrev: http://cr.openjdk.java.net/~sundar/8204321/webrev.00/index.html Thanks, -Sundar From priya.lakshmi.muthuswamy at oracle.com Tue Jun 5 06:44:11 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Tue, 5 Jun 2018 12:14:11 +0530 Subject: RFR:JDK-8190875:modules not listed in overview/index page In-Reply-To: <5B15BB7A.2060504@oracle.com> References: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> <5B11A55A.9040406@oracle.com> <89eb1996-7b5c-c452-8e6c-47fad36615d5@oracle.com> <5B15BB7A.2060504@oracle.com> Message-ID: <591a3410-ca76-9d5f-3f5f-1c84bb963c73@oracle.com> Hi Jon, Thanks for the review. I could have avoided having explicit side-file. updated webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.02/ Thanks, Priya On 6/5/2018 3:51 AM, Jonathan Gibbons wrote: > It seems weird to have a hybrid methodology, such that you have an > explicit side-file (overview.html) but you generate other (source) > files on the fly. > > If you want to keep overview.html as a separate distinct file, it > needs to have a full legal header. Yes, I know it is sorta-silly to > have a 22 line legal header for a 6 line file, but that's the general > rule/guideline, and is also the reason why these days we prefer to > generate those files on the fly. > > You've already got an instance of ToolBox in each of the test cases, > but you only need overview.html in one: testIndexWithOverviewPath > > I recommend using ToolBox.writeFile to create the overview.html file, > so that the test becomes self-contained with no need for the side-file. > > (Side-files are OK if they start getting big and complicated, but > don't ask me for a hard and fast rule of when to use an inline string, > and when to use a side file. But generally, if the file is "small", > generate the file on the fly.) > > -- Jon > > On 06/03/2018 09:07 PM, Priya Lakshmi Muthuswamy wrote: >> Hi Jon, >> >> I have updated the webrev with the suggestions. >> >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.01/ >> >> Thanks, >> Priya >> >> On 6/2/2018 1:28 AM, Jonathan Gibbons wrote: >>> >>> >>> On 06/01/2018 02:34 AM, Priya Lakshmi Muthuswamy wrote: >>>> Hi, >>>> >>>> Kindly review the fix for >>>> https://bugs.openjdk.java.net/browse/JDK-8190875 >>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ >>>> >>>> Thanks, >>>> Priya >>> >>> You are using a single shared src directory, and mutating it in the >>> various test cases. >>> This means that the test cases are not independent, and depend on >>> the (unspecified) >>> order of execution of the test cases. >>> >>> You should create a new copy of the "src" directory as a new >>> subdirectory of the "base" >>> directory in each test case. >>> >>> -- Jon >> > From sundararajan.athijegannathan at oracle.com Tue Jun 5 08:45:30 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Tue, 05 Jun 2018 14:15:30 +0530 Subject: RFR:JDK-8190875:modules not listed in overview/index page In-Reply-To: <591a3410-ca76-9d5f-3f5f-1c84bb963c73@oracle.com> References: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> <5B11A55A.9040406@oracle.com> <89eb1996-7b5c-c452-8e6c-47fad36615d5@oracle.com> <5B15BB7A.2060504@oracle.com> <591a3410-ca76-9d5f-3f5f-1c84bb963c73@oracle.com> Message-ID: <5B164DAA.50204@oracle.com> Looks good. -Sundar On 05/06/18, 12:14 PM, Priya Lakshmi Muthuswamy wrote: > Hi Jon, > > Thanks for the review. > I could have avoided having explicit side-file. > updated webrev : > http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.02/ > > Thanks, > Priya > > On 6/5/2018 3:51 AM, Jonathan Gibbons wrote: >> It seems weird to have a hybrid methodology, such that you have an >> explicit side-file (overview.html) but you generate other (source) >> files on the fly. >> >> If you want to keep overview.html as a separate distinct file, it >> needs to have a full legal header. Yes, I know it is sorta-silly to >> have a 22 line legal header for a 6 line file, but that's the general >> rule/guideline, and is also the reason why these days we prefer to >> generate those files on the fly. >> >> You've already got an instance of ToolBox in each of the test cases, >> but you only need overview.html in one: testIndexWithOverviewPath >> >> I recommend using ToolBox.writeFile to create the overview.html file, >> so that the test becomes self-contained with no need for the side-file. >> >> (Side-files are OK if they start getting big and complicated, but >> don't ask me for a hard and fast rule of when to use an inline >> string, and when to use a side file. But generally, if the file is >> "small", generate the file on the fly.) >> >> -- Jon >> >> On 06/03/2018 09:07 PM, Priya Lakshmi Muthuswamy wrote: >>> Hi Jon, >>> >>> I have updated the webrev with the suggestions. >>> >>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.01/ >>> >>> Thanks, >>> Priya >>> >>> On 6/2/2018 1:28 AM, Jonathan Gibbons wrote: >>>> >>>> >>>> On 06/01/2018 02:34 AM, Priya Lakshmi Muthuswamy wrote: >>>>> Hi, >>>>> >>>>> Kindly review the fix for >>>>> https://bugs.openjdk.java.net/browse/JDK-8190875 >>>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ >>>>> >>>>> Thanks, >>>>> Priya >>>> >>>> You are using a single shared src directory, and mutating it in the >>>> various test cases. >>>> This means that the test cases are not independent, and depend on >>>> the (unspecified) >>>> order of execution of the test cases. >>>> >>>> You should create a new copy of the "src" directory as a new >>>> subdirectory of the "base" >>>> directory in each test case. >>>> >>>> -- Jon >>> >> > From jonathan.gibbons at oracle.com Tue Jun 5 17:16:08 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 5 Jun 2018 10:16:08 -0700 Subject: RFR: JDK-8204303: Add redirect for overview-summary.html Message-ID: The recent change to update javadoc to not generate frames by default means that the overview-summary.html file is no longer generated: the content that was previously in that file is now in the top-level index.html file. This means that any saved bookmarks to the overview-summary.html file are invalid. The fix is to generate a dummy overview-summary.html that simply redirects to the top-level index.html file. The file is only generated when it would otherwise have been generated in frames mode. The file may eventually be removed in an unspecified future release, after suitable explicit warnings have been made. The change leverages the existing code in IndexRedirectWriter.java, by generalizing it to create redirect files from any file to any other file in the doc bundle. JBS: https://bugs.openjdk.java.net/browse/JDK-8204303 Webrev: http://cr.openjdk.java.net/~jjg/8204303/webrev.00/index.html -- Jon From jonathan.gibbons at oracle.com Tue Jun 5 17:20:46 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 5 Jun 2018 10:20:46 -0700 Subject: RFR 8204321: javadoc tests fail after JDK-8203780 In-Reply-To: <5B162C79.5000404@oracle.com> References: <5B162C79.5000404@oracle.com> Message-ID: OK. On 6/4/18 11:23 PM, Sundararajan Athijegannathan wrote: > Please review. > > Bug: https://bugs.openjdk.java.net/browse/JDK-8204321 > Webrev: http://cr.openjdk.java.net/~sundar/8204321/webrev.00/index.html > > Thanks, > -Sundar From sundararajan.athijegannathan at oracle.com Wed Jun 6 03:42:24 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Wed, 06 Jun 2018 09:12:24 +0530 Subject: RFR: JDK-8204303: Add redirect for overview-summary.html In-Reply-To: References: Message-ID: <5B175820.4030104@oracle.com> Looks good. Minor: "private DocPath target;" could be final in IndexRedirectWriter -Sundar On 05/06/18, 10:46 PM, Jonathan Gibbons wrote: > The recent change to update javadoc to not generate frames by default > means that the overview-summary.html file is no longer generated: the > content that was previously in that file is now in the top-level > index.html file. > > This means that any saved bookmarks to the overview-summary.html file > are invalid. > > The fix is to generate a dummy overview-summary.html that simply > redirects to the top-level index.html file. The file is only generated > when it would otherwise have been generated in frames mode. The file > may eventually be removed in an unspecified future release, after > suitable explicit warnings have been made. > > The change leverages the existing code in IndexRedirectWriter.java, by > generalizing it to create redirect files from any file to any other > file in the doc bundle. > > JBS: https://bugs.openjdk.java.net/browse/JDK-8204303 > Webrev: http://cr.openjdk.java.net/~jjg/8204303/webrev.00/index.html > > -- Jon > -------------- next part -------------- An HTML attachment was scrubbed... URL: From hannes.wallnoefer at oracle.com Wed Jun 6 09:40:55 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 6 Jun 2018 11:40:55 +0200 Subject: RFR: JDK-8204303: Add redirect for overview-summary.html In-Reply-To: References: Message-ID: Hi Jon, Looks good to me. Hannes > Am 05.06.2018 um 19:16 schrieb Jonathan Gibbons : > > The recent change to update javadoc to not generate frames by default means that the overview-summary.html file is no longer generated: the content that was previously in that file is now in the top-level index.html file. > > This means that any saved bookmarks to the overview-summary.html file are invalid. > > The fix is to generate a dummy overview-summary.html that simply redirects to the top-level index.html file. The file is only generated when it would otherwise have been generated in frames mode. The file may eventually be removed in an unspecified future release, after suitable explicit warnings have been made. > > The change leverages the existing code in IndexRedirectWriter.java, by generalizing it to create redirect files from any file to any other file in the doc bundle. > > JBS: https://bugs.openjdk.java.net/browse/JDK-8204303 > Webrev: http://cr.openjdk.java.net/~jjg/8204303/webrev.00/index.html > > -- Jon > From jonathan.gibbons at oracle.com Wed Jun 6 20:53:02 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 06 Jun 2018 13:53:02 -0700 Subject: RFR:JDK-8190875:modules not listed in overview/index page In-Reply-To: <591a3410-ca76-9d5f-3f5f-1c84bb963c73@oracle.com> References: <02a3ff29-2fc3-a855-377e-6b3480bbec00@oracle.com> <5B11A55A.9040406@oracle.com> <89eb1996-7b5c-c452-8e6c-47fad36615d5@oracle.com> <5B15BB7A.2060504@oracle.com> <591a3410-ca76-9d5f-3f5f-1c84bb963c73@oracle.com> Message-ID: <5B1849AE.5050308@oracle.com> Better. Thanks. -- Jon On 06/04/2018 11:44 PM, Priya Lakshmi Muthuswamy wrote: > Hi Jon, > > Thanks for the review. > I could have avoided having explicit side-file. > updated webrev : > http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.02/ > > Thanks, > Priya > > On 6/5/2018 3:51 AM, Jonathan Gibbons wrote: >> It seems weird to have a hybrid methodology, such that you have an >> explicit side-file (overview.html) but you generate other (source) >> files on the fly. >> >> If you want to keep overview.html as a separate distinct file, it >> needs to have a full legal header. Yes, I know it is sorta-silly to >> have a 22 line legal header for a 6 line file, but that's the general >> rule/guideline, and is also the reason why these days we prefer to >> generate those files on the fly. >> >> You've already got an instance of ToolBox in each of the test cases, >> but you only need overview.html in one: testIndexWithOverviewPath >> >> I recommend using ToolBox.writeFile to create the overview.html file, >> so that the test becomes self-contained with no need for the side-file. >> >> (Side-files are OK if they start getting big and complicated, but >> don't ask me for a hard and fast rule of when to use an inline >> string, and when to use a side file. But generally, if the file is >> "small", generate the file on the fly.) >> >> -- Jon >> >> On 06/03/2018 09:07 PM, Priya Lakshmi Muthuswamy wrote: >>> Hi Jon, >>> >>> I have updated the webrev with the suggestions. >>> >>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.01/ >>> >>> Thanks, >>> Priya >>> >>> On 6/2/2018 1:28 AM, Jonathan Gibbons wrote: >>>> >>>> >>>> On 06/01/2018 02:34 AM, Priya Lakshmi Muthuswamy wrote: >>>>> Hi, >>>>> >>>>> Kindly review the fix for >>>>> https://bugs.openjdk.java.net/browse/JDK-8190875 >>>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8190875/webrev.00/ >>>>> >>>>> Thanks, >>>>> Priya >>>> >>>> You are using a single shared src directory, and mutating it in the >>>> various test cases. >>>> This means that the test cases are not independent, and depend on >>>> the (unspecified) >>>> order of execution of the test cases. >>>> >>>> You should create a new copy of the "src" directory as a new >>>> subdirectory of the "base" >>>> directory in each test case. >>>> >>>> -- Jon >>> >> > From jonathan.gibbons at oracle.com Thu Jun 7 18:57:26 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 07 Jun 2018 11:57:26 -0700 Subject: RFR: JDK-8204330: Javadoc IllegalArgumentException: HTML special chars in constant value Message-ID: <5B198016.4030305@oracle.com> Please review a simple fix for an issue that caused IllegalArgumentException when processing a constant value containing the special HTML characters, < & >. In HTMLWriter, the fix is to simply remove the inappropriate restriction on the presence of the special HTML chars. The existing use of StringContent will handle the characters correctly, by suitably encoding them. In TagletWriter, the inappropriate use of RawHtml is replaced by the use of StringContent. A new test case is added to the existing test for the {@value} tag. It verifies the correct encoding of the characters, and verifies the absence of unencoded characters and the absence of any exceptions. JBS: https://bugs.openjdk.java.net/browse/JDK-8204330 Webrev: http://cr.openjdk.java.net/~jjg/8204330/webrev.00/index.html -- Jon From jonathan.gibbons at oracle.com Thu Jun 7 22:19:24 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 07 Jun 2018 15:19:24 -0700 Subject: RFR: JDK-8149565: -locale option issues Message-ID: <5B19AF6C.7000900@oracle.com> Please review a relatively simple fix to a problem that was found a while back relating to the handling of the -locale option. The fix is to change some old code, that did not work on all locales installed in a standard JDK build, with the use of Locale.forLanguageTag, added in JDK 7. This method supports IETF BCP 47 language tag strings. The test is removed from the problem list and updated to work correctly. The primary error in the test as originally written was that the doclet invocation would create the doclet instance in a distinct classloader, and thus not share static members, as was clearly the intent. JBS: https://bugs.openjdk.java.net/browse/JDK-8149565 Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html -- Jon From jonathan.gibbons at oracle.com Thu Jun 7 23:45:31 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 07 Jun 2018 16:45:31 -0700 Subject: RFR: JDK-8149565: -locale option issues In-Reply-To: <5B19AF6C.7000900@oracle.com> References: <5B19AF6C.7000900@oracle.com> Message-ID: <5B19C39B.3090306@oracle.com> Improved webrev, that uses Locale.Builder to detect syntactically bad locales. Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html -- Jon On 06/07/2018 03:19 PM, Jonathan Gibbons wrote: > Please review a relatively simple fix to a problem that was found a > while back relating to the handling of the -locale option. > > The fix is to change some old code, that did not work on all locales > installed in a standard JDK build, with the use of > Locale.forLanguageTag, added in JDK 7. This method supports IETF BCP > 47 language tag strings. > > The test is removed from the problem list and updated to work > correctly. The primary error in the test as originally written was > that the doclet invocation would create the doclet instance in a > distinct classloader, and thus not share static members, as was > clearly the intent. > > JBS: https://bugs.openjdk.java.net/browse/JDK-8149565 > Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html > > -- Jon From hannes.wallnoefer at oracle.com Fri Jun 8 14:13:15 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Fri, 8 Jun 2018 16:13:15 +0200 Subject: RFR: JDK-8149565: -locale option issues In-Reply-To: <5B19C39B.3090306@oracle.com> References: <5B19AF6C.7000900@oracle.com> <5B19C39B.3090306@oracle.com> Message-ID: I noticed that the old getLocale code used underscore as separator while LanguageTag uses hyphen. Isn?t that a problem? The main method of the VerifyLocale test uses a mix of tab and spaces for indentation. Otherwise looks good to me. Hannes > Am 08.06.2018 um 01:45 schrieb Jonathan Gibbons : > > Improved webrev, that uses Locale.Builder to detect syntactically bad locales. > > Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html > > -- Jon > > On 06/07/2018 03:19 PM, Jonathan Gibbons wrote: >> Please review a relatively simple fix to a problem that was found a while back relating to the handling of the -locale option. >> >> The fix is to change some old code, that did not work on all locales installed in a standard JDK build, with the use of Locale.forLanguageTag, added in JDK 7. This method supports IETF BCP 47 language tag strings. >> >> The test is removed from the problem list and updated to work correctly. The primary error in the test as originally written was that the doclet invocation would create the doclet instance in a distinct classloader, and thus not share static members, as was clearly the intent. >> >> JBS: https://bugs.openjdk.java.net/browse/JDK-8149565 >> Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html >> >> -- Jon > From jonathan.gibbons at oracle.com Fri Jun 8 15:18:38 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 8 Jun 2018 08:18:38 -0700 Subject: RFR: JDK-8149565: -locale option issues In-Reply-To: References: <5B19AF6C.7000900@oracle.com> <5B19C39B.3090306@oracle.com> Message-ID: <35520888-c7aa-acaa-62fe-804a947b1184@oracle.com> LanguageTag seems to be recommended, but to provide temporary compatibility, the doclet converts '_' to '-' to allow the old usage. An arguably better solution would be to try the string unmodified, and only if it fails, try converting '_' to '-' and see if that is better ... if that succeeds, maybe javadoc should write a warning.?? But that is all more than I wanted to do at this stage in the release. -- Jon On 6/8/18 7:13 AM, Hannes Walln?fer wrote: > I noticed that the old getLocale code used underscore as separator while LanguageTag uses hyphen. Isn?t that a problem? > > The main method of the VerifyLocale test uses a mix of tab and spaces for indentation. > > Otherwise looks good to me. > > Hannes > > >> Am 08.06.2018 um 01:45 schrieb Jonathan Gibbons : >> >> Improved webrev, that uses Locale.Builder to detect syntactically bad locales. >> >> Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html >> >> -- Jon >> >> On 06/07/2018 03:19 PM, Jonathan Gibbons wrote: >>> Please review a relatively simple fix to a problem that was found a while back relating to the handling of the -locale option. >>> >>> The fix is to change some old code, that did not work on all locales installed in a standard JDK build, with the use of Locale.forLanguageTag, added in JDK 7. This method supports IETF BCP 47 language tag strings. >>> >>> The test is removed from the problem list and updated to work correctly. The primary error in the test as originally written was that the doclet invocation would create the doclet instance in a distinct classloader, and thus not share static members, as was clearly the intent. >>> >>> JBS: https://bugs.openjdk.java.net/browse/JDK-8149565 >>> Webrev: http://cr.openjdk.java.net/~jjg/8149565/webrev.00/index.html >>> >>> -- Jon From priya.lakshmi.muthuswamy at oracle.com Mon Jun 11 07:13:30 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 11 Jun 2018 12:43:30 +0530 Subject: RFR: JDK-8204666: javadoc should be updated to use jquery 3.3.1 Message-ID: <67bb9aa2-8c6f-a308-6707-d58e9534a4bf@oracle.com> Hi, Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8204666 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8204666/webrev.00/ jquery-migrate is included to solve incompatibility issues between jQuery 3.x and jQuery UI 1.x Thanks, Priya From sundararajan.athijegannathan at oracle.com Mon Jun 11 11:05:37 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Mon, 11 Jun 2018 16:35:37 +0530 Subject: RFR: JDK-8204666: javadoc should be updated to use jquery 3.3.1 In-Reply-To: <67bb9aa2-8c6f-a308-6707-d58e9534a4bf@oracle.com> References: <67bb9aa2-8c6f-a308-6707-d58e9534a4bf@oracle.com> Message-ID: <5B1E5781.3090703@oracle.com> jquery.md should use 2018 as the copyright year I think - based on copyright date "Date: 2018-01-20T17:24Z" in jquery-3.3.1.js file. Other than that +1 -Sundar On 11/06/18, 12:43 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8204666 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8204666/webrev.00/ > > jquery-migrate is included to solve incompatibility issues between > jQuery 3.x and jQuery UI 1.x > > Thanks, > Priya From priya.lakshmi.muthuswamy at oracle.com Thu Jun 14 11:35:57 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Thu, 14 Jun 2018 17:05:57 +0530 Subject: RFR: JDK-8204666 : javadoc should be updated to use jquery 3.3.1 Message-ID: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> Hi, Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8202624 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202624/webrev.00/ Thanks, Priya From hannes.wallnoefer at oracle.com Fri Jun 15 07:43:50 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Fri, 15 Jun 2018 09:43:50 +0200 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules Message-ID: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. The sorting order for types, members, and search tags is not changed. The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. Please review: Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 Thanks, Hannes From priya.lakshmi.muthuswamy at oracle.com Fri Jun 15 12:42:59 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Fri, 15 Jun 2018 18:12:59 +0530 Subject: RFR: JDK-JDK-8187288 : bad (no) wrapping for modifier and type column Message-ID: <6d1989be-ea64-e233-dfb0-aba768fc8915@oracle.com> Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8187288 webrev:? http://cr.openjdk.java.net/~pmuthuswamy/8187288/webrev.00/ Thanks, Priya From priya.lakshmi.muthuswamy at oracle.com Mon Jun 18 03:49:29 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 18 Jun 2018 09:19:29 +0530 Subject: RFR: JDK-8202624 : javadoc generates references to enum constructors, which are not documented In-Reply-To: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> References: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> Message-ID: Hi, ?Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8202624 ?webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202624/webrev.00/ Thanks, Priya From priya.lakshmi.muthuswamy at oracle.com Mon Jun 18 06:07:59 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 18 Jun 2018 11:37:59 +0530 Subject: RFR: JDK-8205148: Turn off logging in jQuery-migrate Message-ID: <01014eb9-313c-767a-c54a-34d52adfc8b0@oracle.com> Hi, Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8205148 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205148/webrev.00/ Thanks, Priya From sundararajan.athijegannathan at oracle.com Mon Jun 18 07:10:51 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Mon, 18 Jun 2018 12:40:51 +0530 Subject: RFR: JDK-8205148: Turn off logging in jQuery-migrate In-Reply-To: <01014eb9-313c-767a-c54a-34d52adfc8b0@oracle.com> References: <01014eb9-313c-767a-c54a-34d52adfc8b0@oracle.com> Message-ID: <5B275AFB.5090201@oracle.com> Looks good -Sundar On 18/06/18, 11:37 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8205148 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205148/webrev.00/ > > Thanks, > Priya From sundararajan.athijegannathan at oracle.com Mon Jun 18 07:12:04 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Mon, 18 Jun 2018 12:42:04 +0530 Subject: RFR: JDK-8202624 : javadoc generates references to enum constructors, which are not documented In-Reply-To: References: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> Message-ID: <5B275B44.7050506@oracle.com> Looks good. -Sundar On 18/06/18, 9:19 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8202624 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202624/webrev.00/ > > Thanks, > Priya > From sundararajan.athijegannathan at oracle.com Mon Jun 18 07:13:47 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Mon, 18 Jun 2018 12:43:47 +0530 Subject: RFR: JDK-8204666 : javadoc should be updated to use jquery 3.3.1 In-Reply-To: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> References: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> Message-ID: <5B275BAB.3000201@oracle.com> Webrev URL seems to be of different bug. -Sundar On 14/06/18, 5:05 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8202624 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202624/webrev.00/ > > Thanks, > Priya From priya.lakshmi.muthuswamy at oracle.com Mon Jun 18 08:57:46 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Mon, 18 Jun 2018 14:27:46 +0530 Subject: RFR: JDK-8204666 : javadoc should be updated to use jquery 3.3.1 In-Reply-To: <5B275BAB.3000201@oracle.com> References: <9d131edb-340f-29d7-9b95-2c5922bfd36c@oracle.com> <5B275BAB.3000201@oracle.com> Message-ID: I'm sorry subject was wrong. I edited the subject and sent it once again. http://mail.openjdk.java.net/pipermail/javadoc-dev/2018-June/000542.html. -Priya On 6/18/2018 12:43 PM, Sundararajan Athijegannathan wrote: > Webrev URL seems to be of different bug. > > -Sundar > > On 14/06/18, 5:05 PM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review fix for https://bugs.openjdk.java.net/browse/JDK-8202624 >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8202624/webrev.00/ >> >> Thanks, >> Priya From rick.hillegas at gmail.com Fri Jun 15 03:08:35 2018 From: rick.hillegas at gmail.com (Rick Hillegas) Date: Thu, 14 Jun 2018 20:08:35 -0700 Subject: a second question: running javadoc against multiple modules In-Reply-To: <94e6cad1-b66c-7c71-ebb9-304857de2729@oracle.com> References: <5B0D9CE6.2090308@oracle.com> <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com> <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> <94e6cad1-b66c-7c71-ebb9-304857de2729@oracle.com> Message-ID: <3161401f-7cbf-e30a-9ac4-cfc186992838@gmail.com> Hi Jon, Thanks again for answering my first question. I have made some progress toward generating module-aware javadoc for the Apache Derby project. Now I have a second problem which puzzles me. The following command successfully generates module-aware javadoc for almost all of the packages in one of the Derby modules: javadoc -d ./build/javadoc \ ? --module-source-path $derbyRoot/java \ ? --module-path $derbyRoot/classes/stubs/felix \ ? --module org.apache.derby.client \ ? -Xdoclint:none \ ? -subpackages \ ? org.apache.derby.client.am org.apache.derby.client org.apache.derby.client.net However, when I tack another package onto the end of the package list... javadoc -d ./build/javadoc \ ? --module-source-path $derbyRoot/java \ ? --module-path $derbyRoot/classes/stubs/felix \ ? --module org.apache.derby.client \ ? -Xdoclint:none \ ? -subpackages \ ? org.apache.derby.client.am org.apache.derby.client org.apache.derby.client.net org.apache.derby.loc.client ...the javadoc command aborts as follows... Loading source files for package org.apache.derby.client... Loading source files for package org.apache.derby.client.net... Loading source files for package org.apache.derby.loc.client... javadoc: error - No source files for package org.apache.derby.loc.client 1 error See the end of this message for the directory tree of this module. I would appreciate any advice you can give me about what I am doing wrong. Thanks, -Rick trunk/java/org.apache.derby.client trunk/java/org.apache.derby.client/build.xml trunk/java/org.apache.derby.client/module-info.java trunk/java/org.apache.derby.client/org trunk/java/org.apache.derby.client/org/apache trunk/java/org.apache.derby.client/org/apache/derby trunk/java/org.apache.derby.client/org/apache/derby/client trunk/java/org.apache.derby.client/org/apache/derby/client/am trunk/java/org.apache.derby.client/org/apache/derby/client/am/Agent.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/AsciiStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/BlobLocatorInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/BlobLocatorOutputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/BlobOutputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ByteArrayCombinerStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/CachingLogicalConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/CallableLocatorProcedures.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientBlob.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientCallableStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientCallableStatement42.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientClob.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientDatabaseMetaData.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientJDBCObjectFactory.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientMessageId.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientParameterMetaData.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientPreparedStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientPreparedStatement42.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientResultSet.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientSavepoint.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClientTypes.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClobLocatorInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClobLocatorOutputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClobLocatorReader.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClobLocatorWriter.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClobOutputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ClobWriter.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/CloseFilterInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ColumnMetaData.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Configuration.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ConnectionCallbackInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/CrossConverters.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Cursor.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/DateTime.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/DateTimeValue.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Decimal.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Diagnosable.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/DisconnectException.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/EncryptionManager.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ExceptionFormatter.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/FailedProperties40.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/FloatingPoint.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Lob.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LOBStateTracker.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalCallableStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalCallableStatement42.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalDatabaseMetaData.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalPreparedStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalPreparedStatement42.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogicalStatementEntity.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/LogWriter.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/MaterialPreparedStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/MaterialStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/PreparedStatementCallbackInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ProductLevel.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/ResultSetCallbackInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Section.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/SectionManager.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/SignedBinary.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Sqlca.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/SqlCode.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/SqlException.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/SQLExceptionFactory.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/SqlWarning.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/StatementCacheInteractor.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/StatementCallbackInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/stmtcache trunk/java/org.apache.derby.client/org/apache/derby/client/am/stmtcache/JDBCStatementCache.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/stmtcache/package.html trunk/java/org.apache.derby.client/org/apache/derby/client/am/stmtcache/StatementKey.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/stmtcache/StatementKeyFactory.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/UnitOfWorkListener.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/UpdateSensitiveBlobLocatorInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/UpdateSensitiveClobLocatorInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/UpdateSensitiveClobLocatorReader.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/UpdateSensitiveLOBLocatorInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Utils.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Utils42.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/Version.java trunk/java/org.apache.derby.client/org/apache/derby/client/am/XaException.java trunk/java/org.apache.derby.client/org/apache/derby/client/BasicClientDataSource.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientAutoloadedDriver.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientConnectionPoolDataSourceInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientDataSourceFactory.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientDataSourceInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientPooledConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientXAConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientXADataSourceInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/ClientXid.java trunk/java/org.apache.derby.client/org/apache/derby/client/net trunk/java/org.apache.derby.client/org/apache/derby/client/net/CcsidManager.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ClientJDBCObjectFactoryImpl.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ClientJDBCObjectFactoryImpl42.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/CodePoint.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/CodePointNameTable.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ConnectionReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ConnectionReplyInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ConnectionRequestInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/DssConstants.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/EbcdicCcsidManager.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/EncodedInputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/FdocaConstants.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/FdocaSimpleDataArray.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetAgent.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetCallableStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetConfiguration.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetConnectionReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetConnectionRequest.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetCursor.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetDatabaseMetaData.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetLogWriter.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetPackageReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetPackageRequest.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetPreparedStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetResultSet.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetResultSet42.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetResultSetReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetResultSetRequest.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetSqlca.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetSqldta.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetStatement.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetStatementReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetStatementRequest.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetXACallInfo.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetXAConnection.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetXAConnectionReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetXAConnectionRequest.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/NetXAResource.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/OpenSocketAction.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/PublicBufferOutputStream.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/Reply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/Request.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ResultSetReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ResultSetReplyInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/ResultSetRequestInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/StatementReply.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/StatementReplyInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/StatementRequestInterface.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/Typdef.java trunk/java/org.apache.derby.client/org/apache/derby/client/net/Utf8CcsidManager.java trunk/java/org.apache.derby.client/org/apache/derby/loc trunk/java/org.apache.derby.client/org/apache/derby/loc/client trunk/java/org.apache.derby.client/org/apache/derby/loc/client/clientmessagesProviderImpl.java -------------- next part -------------- An HTML attachment was scrubbed... URL: From rick.hillegas at gmail.com Sun Jun 17 22:45:04 2018 From: rick.hillegas at gmail.com (Rick Hillegas) Date: Sun, 17 Jun 2018 15:45:04 -0700 Subject: generating module-aware javadoc for internal packages In-Reply-To: <3161401f-7cbf-e30a-9ac4-cfc186992838@gmail.com> References: <5B0D9CE6.2090308@oracle.com> <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com> <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> <94e6cad1-b66c-7c71-ebb9-304857de2729@oracle.com> <3161401f-7cbf-e30a-9ac4-cfc186992838@gmail.com> Message-ID: <0ee9398b-1477-305f-bcc2-c2b3ed841e10@gmail.com> I would appreciate your advice about how to generate module-aware documentation for internal packages which have not been exported by the corresponding module info. Given the attached project, the following command works fine... javadoc -d ./build/javadoc \ ? -Xdoclint:none \ ? --module-source-path ./java \ ? --module org.test.mymodule \ ? visiblepackage However, the following command... javadoc -d ./build/javadoc \ ? -Xdoclint:none \ ? --module-source-path ./java \ ? --module org.test.mymodule \ ? visiblepackage invisiblepackage ...dies with the following diagnostic messages: Loading source files for package visiblepackage... Loading source files for package invisiblepackage... javadoc: error - No source files for package invisiblepackage 1 error Thanks, -Rick -------------- next part -------------- An HTML attachment was scrubbed... URL: -------------- next part -------------- A non-text attachment was scrubbed... Name: zdoc.tar Type: application/x-tar Size: 9216 bytes Desc: not available URL: From jonathan.gibbons at oracle.com Mon Jun 18 18:23:39 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 18 Jun 2018 11:23:39 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> Message-ID: <5B27F8AB.9020705@oracle.com> Minor issues to address: HtmlConfiguration, 397, 406: You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. SearchIndexItem If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. Style issue: Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) -- Jon On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: > This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. > > The sorting order for types, members, and search tags is not changed. > > The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. > > Please review: > > Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ > Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 > > Thanks, > Hannes From jonathan.gibbons at oracle.com Tue Jun 19 00:00:30 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 18 Jun 2018 17:00:30 -0700 Subject: generating module-aware javadoc for internal packages In-Reply-To: <0ee9398b-1477-305f-bcc2-c2b3ed841e10@gmail.com> References: <5B0D9CE6.2090308@oracle.com> <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com> <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> <94e6cad1-b66c-7c71-ebb9-304857de2729@oracle.com> <3161401f-7cbf-e30a-9ac4-cfc186992838@gmail.com> <0ee9398b-1477-305f-bcc2-c2b3ed841e10@gmail.com> Message-ID: <5B28479E.7080000@oracle.com> Rick, You should look at the new --show-* options which provide a generalization of the previously available options -public, -protected, -package and -private. From the command-line help: --show-members Specifies which members (fields, methods, etc.) will be documented, where value can be one of "public", "protected", "package" or "private". The default is "protected", which will show public and protected members, "public" will show only public members, "package" will show public, protected and package members and "private" will show all members. --show-module-contents Specifies the documentation granularity of module declarations. Possible values are "api" or "all". --show-packages Specifies which modules packages will be documented. Possible values are "exported" or "all" packages. --show-types Specifies which types (classes, interfaces, etc.) will be documented, where value can be one of "public", "protected", "package" or "private". The default is "protected", which will show public and protected types, "public" will show only public types, "package" will show public, protected and package types and "private" will show all types. The older options map onto specific combinations of the above new options. -package Show package/protected/public types and members. For named modules, show all packages and all module details. -private Show all types and members. For named modules, show all packages and all module details. -protected Show protected/public types and members (default). For named modules, show exported packages and the module's API. -public Show only public types and members. For named modules, show exported packages and the module's API. You may also want to note that package names can be specified in the form module/package if you wish to disambiguate the module containing a specific package. -- Jon On 06/17/2018 03:45 PM, Rick Hillegas wrote: > I would appreciate your advice about how to generate module-aware > documentation for internal packages which have not been exported by > the corresponding module info. > > Given the attached project, the following command works fine... > > javadoc -d ./build/javadoc \ > -Xdoclint:none \ > --module-source-path ./java \ > --module org.test.mymodule \ > visiblepackage > > However, the following command... > > javadoc -d ./build/javadoc \ > -Xdoclint:none \ > --module-source-path ./java \ > --module org.test.mymodule \ > visiblepackage invisiblepackage > > ...dies with the following diagnostic messages: > > Loading source files for package visiblepackage... > Loading source files for package invisiblepackage... > javadoc: error - No source files for package invisiblepackage > 1 error > > Thanks, > -Rick > -------------- next part -------------- An HTML attachment was scrubbed... URL: From priya.lakshmi.muthuswamy at oracle.com Tue Jun 19 04:36:57 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Tue, 19 Jun 2018 10:06:57 +0530 Subject: RFR: JDK-8205160: jQuery UI license file to be updated to the revision present. Message-ID: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8205160 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.00/ Thanks, Priya From hannes.wallnoefer at oracle.com Tue Jun 19 10:03:30 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 19 Jun 2018 12:03:30 +0200 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <5B27F8AB.9020705@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> Message-ID: <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> Thanks for the review, Jon. I?ve uploaded a new webrev to address the issues you brought up: http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. Hannes > Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : > > Minor issues to address: > > HtmlConfiguration, 397, 406: > You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. > > SearchIndexItem > If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. > > Style issue: > > Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) > > -- Jon > > > On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >> >> The sorting order for types, members, and search tags is not changed. >> >> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >> >> Please review: >> >> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >> >> Thanks, >> Hannes > From rick.hillegas at gmail.com Tue Jun 19 01:25:30 2018 From: rick.hillegas at gmail.com (Rick Hillegas) Date: Mon, 18 Jun 2018 18:25:30 -0700 Subject: generating module-aware javadoc for internal packages In-Reply-To: <5B28479E.7080000@oracle.com> References: <5B0D9CE6.2090308@oracle.com> <0a4861fd-4b72-2b47-2a55-a3969ce8527c@gmail.com> <16b70336-f344-f8c5-68a6-ce0183b000b7@gmail.com> <94e6cad1-b66c-7c71-ebb9-304857de2729@oracle.com> <3161401f-7cbf-e30a-9ac4-cfc186992838@gmail.com> <0ee9398b-1477-305f-bcc2-c2b3ed841e10@gmail.com> <5B28479E.7080000@oracle.com> Message-ID: <02712ce7-ec24-220b-66e5-69fc4b4d999e@gmail.com> Thanks, Jon. That was very helpful. The following command generates documentation for the internal, unexported package: javadoc -d ./build/javadoc \ ? -Xdoclint:none \ ? --module-source-path ./java \ ? --show-module-contents all \ ? --show-packages all \ ? --module org.test.mymodule On 6/18/18 5:00 PM, Jonathan Gibbons wrote: > Rick, > > You should look at the new --show-* options which provide a > generalization of the previously available options -public, > -protected, -package and -private. > > From the command-line help: > > ??? --show-members > ????????????????? Specifies which members (fields, methods, etc.) will be > ????????????????? documented, where value can be one of "public", > "protected", > ????????????????? "package" or "private". The default is "protected", > which will > ????????????????? show public and protected members, "public" will > show only > ????????????????? public members, "package" will show public, > protected and > ????????????????? package members and "private" will show all members. > ??? --show-module-contents > ????????????????? Specifies the documentation granularity of module > ????????????????? declarations. Possible values are "api" or "all". > ??? --show-packages > ????????????????? Specifies which modules packages will be documented. > Possible > ????????????????? values are "exported" or "all" packages. > ??? --show-types > ????????????????? Specifies which types (classes, interfaces, etc.) > will be > ????????????????? documented, where value can be one of "public", > "protected", > ????????????????? "package" or "private". The default is "protected", > which will > ????????????????? show public and protected types, "public" will show only > ????????????????? public types, "package" will show public, protected and > ????????????????? package types and "private" will show all types. > > The older options map onto specific combinations of the above new options. > > ??? -package > ????????????????? Show package/protected/public types and members. For > ????????????????? named modules, show all packages and all module details. > ??? -private > ????????????????? Show all types and members. For named modules, > ????????????????? show all packages and all module details. > ??? -protected > ????????????????? Show protected/public types and members (default). For > ????????????????? named modules, show exported packages and the > module's API. > ??? -public > ????????????????? Show only public types and members. For named modules, > ????????????????? show exported packages and the module's API. > > > You may also want to note that package names can be specified in the form > > module/package > > if you wish to disambiguate the module containing a specific package. > > -- Jon > > > On 06/17/2018 03:45 PM, Rick Hillegas wrote: >> I would appreciate your advice about how to generate module-aware >> documentation for internal packages which have not been exported by >> the corresponding module info. >> >> Given the attached project, the following command works fine... >> >> javadoc -d ./build/javadoc \ >> ? -Xdoclint:none \ >> ? --module-source-path ./java \ >> ? --module org.test.mymodule \ >> ? visiblepackage >> >> However, the following command... >> >> javadoc -d ./build/javadoc \ >> ? -Xdoclint:none \ >> ? --module-source-path ./java \ >> ? --module org.test.mymodule \ >> ? visiblepackage invisiblepackage >> >> ...dies with the following diagnostic messages: >> >> Loading source files for package visiblepackage... >> Loading source files for package invisiblepackage... >> javadoc: error - No source files for package invisiblepackage >> 1 error >> >> Thanks, >> -Rick >> > -------------- next part -------------- An HTML attachment was scrubbed... URL: From sgehwolf at redhat.com Tue Jun 19 12:01:06 2018 From: sgehwolf at redhat.com (Severin Gehwolf) Date: Tue, 19 Jun 2018 14:01:06 +0200 Subject: [8u] RFR: 8061305: Javadoc crashes when method name ends with "Property" Message-ID: Hi, Could I please get a review of this backport of JDK-8061305 for JDK 8u? JDK-8061305 is in JDK 9+ for a long time now and we've been using this patch in Fedora for years. The actual patch to VisibleMemberMap.java hasn't changed (post-path-unshuffeling) from JDK 9, but the tests went through great lengths of refactoring in later JDK versions. Thus, I've gone down the route of writing a minimal test case for JDK 8 using the old-style testing. Bug: https://bugs.openjdk.java.net/browse/JDK-8061305 webrev: http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/webrev.01/ Testing: New regression test, test/com/sun/javadoc/ Before: passed: 139; failed: 1; error: 2 After: Test results: passed: 140; error: 2 The tests in error are marked with @ignore. Thoughts? Thanks, Severin From jonathan.gibbons at oracle.com Tue Jun 19 21:06:38 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 19 Jun 2018 14:06:38 -0700 Subject: RFR: JDK-8205160: jQuery UI license file to be updated to the revision present. In-Reply-To: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> References: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> Message-ID: <5B29705E.4000401@oracle.com> Priya, Why are you (just) adding a file; is there not an older file that needs to be updated/removed as well? -- Jon On 06/18/2018 09:36 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8205160 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.00/ > > Thanks, > Priya > > From priya.lakshmi.muthuswamy at oracle.com Wed Jun 20 03:08:49 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Wed, 20 Jun 2018 08:38:49 +0530 Subject: RFR: JDK-8205160: jQuery UI license file to be updated to the revision present. In-Reply-To: <5B29705E.4000401@oracle.com> References: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> <5B29705E.4000401@oracle.com> Message-ID: <84f7000e-037f-d89e-813d-5102d5a581e5@oracle.com> Hi Jon, jQuery UI license file was not there in the legal directory. We have for jQuery, jszip and pako. Regards, Priya On 6/20/2018 2:36 AM, Jonathan Gibbons wrote: > Priya, > > Why are you (just) adding a file; is there not an older file that > needs to be updated/removed as well? > > -- Jon > > On 06/18/2018 09:36 PM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the fix for >> https://bugs.openjdk.java.net/browse/JDK-8205160 >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.00/ >> >> Thanks, >> Priya >> >> > From sundararajan.athijegannathan at oracle.com Wed Jun 20 05:10:01 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Wed, 20 Jun 2018 10:40:01 +0530 Subject: RFR: JDK-8205160: jQuery UI license file to be updated to the revision present. In-Reply-To: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> References: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> Message-ID: <5B29E1A9.2060807@oracle.com> Looks good -Sundar On 19/06/18, 10:06 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8205160 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.00/ > > Thanks, > Priya > > From priya.lakshmi.muthuswamy at oracle.com Wed Jun 20 07:39:08 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Wed, 20 Jun 2018 13:09:08 +0530 Subject: RFR: JDK-8205160: jQuery UI license file to be updated to the revision present. In-Reply-To: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> References: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> Message-ID: Hi, As requested by Arvind, replaced the pre tags with ``` updated webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.01/ Thanks, Priya On 6/19/2018 10:06 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8205160 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.00/ > > Thanks, > Priya > > From priya.lakshmi.muthuswamy at oracle.com Thu Jun 21 06:06:34 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Thu, 21 Jun 2018 11:36:34 +0530 Subject: RFR: JDK-8205160: jQuery UI license file to be updated to the revision present. In-Reply-To: References: <665a7712-cbce-795b-0cbc-54993e17fc02@oracle.com> Message-ID: Including jquery-migrate license as well. Also replacing pre tags with ``` in recently modified md files : jquery,jqueryUI,jquery-migrate Thanks, Priya On 6/20/2018 1:09 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > As requested by Arvind, replaced the pre tags with ``` > updated webrev : > http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.01/ > > Thanks, > Priya > > On 6/19/2018 10:06 AM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the fix for >> https://bugs.openjdk.java.net/browse/JDK-8205160 >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8205160/webrev.00/ >> >> Thanks, >> Priya >> >> > From jonathan.gibbons at oracle.com Fri Jun 22 21:22:14 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 22 Jun 2018 14:22:14 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> Message-ID: <5B2D6886.6050801@oracle.com> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. -- Jon On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: > Thanks for the review, Jon. > > I?ve uploaded a new webrev to address the issues you brought up: > > http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ > > Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. > > I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. > > Hannes > > >> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >> >> Minor issues to address: >> >> HtmlConfiguration, 397, 406: >> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >> >> SearchIndexItem >> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >> >> Style issue: >> >> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >> >> -- Jon >> >> >> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>> >>> The sorting order for types, members, and search tags is not changed. >>> >>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>> >>> Please review: >>> >>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>> >>> Thanks, >>> Hannes From jonathan.gibbons at oracle.com Fri Jun 22 21:33:43 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 22 Jun 2018 14:33:43 -0700 Subject: [8u] RFR: 8061305: Javadoc crashes when method name ends with "Property" In-Reply-To: References: Message-ID: <5B2D6B37.20308@oracle.com> The basic changes look OK, although the convention is to add the legal header on even small examples like test/com/sun/javadoc/testMethodEndingInProperty/Test.java. (Not so applicable here, I note that in new javadoc tests in newer releases of JDK, the convention is more to write tiny files like that on the fly. There are various support libraries to make that easy to do.) I generally recommend using the jtreg option -ignore:quiet to suppress running tests with @ignore. Let me know if you need me to sponsor the change. -- Jon On 06/19/2018 05:01 AM, Severin Gehwolf wrote: > Hi, > > Could I please get a review of this backport of JDK-8061305 for JDK 8u? > JDK-8061305 is in JDK 9+ for a long time now and we've been using this > patch in Fedora for years. The actual patch to VisibleMemberMap.java > hasn't changed (post-path-unshuffeling) from JDK 9, but the tests went > through great lengths of refactoring in later JDK versions. Thus, I've > gone down the route of writing a minimal test case for JDK 8 using the > old-style testing. > > Bug: https://bugs.openjdk.java.net/browse/JDK-8061305 > webrev: http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/webrev.01/ > > Testing: New regression test, > test/com/sun/javadoc/ > Before: passed: 139; failed: 1; error: 2 > After: Test results: passed: 140; error: 2 > > The tests in error are marked with @ignore. Thoughts? > > Thanks, > Severin From sgehwolf at redhat.com Mon Jun 25 09:02:43 2018 From: sgehwolf at redhat.com (Severin Gehwolf) Date: Mon, 25 Jun 2018 11:02:43 +0200 Subject: [8u] RFR: 8061305: Javadoc crashes when method name ends with "Property" In-Reply-To: <5B2D6B37.20308@oracle.com> References: <5B2D6B37.20308@oracle.com> Message-ID: Hi Jon, Thanks for the review! On Fri, 2018-06-22 at 14:33 -0700, Jonathan Gibbons wrote: > The basic changes look OK, although the convention is to add the > legal > header on even small examples like > test/com/sun/javadoc/testMethodEndingInProperty/Test.java. OK, added. > (Not so applicable here, I note that in new javadoc tests in newer > releases of JDK, the convention is more to write tiny files like that on > the fly. There are various support libraries to make that easy to do.) Right. > I generally recommend using the jtreg option -ignore:quiet to suppress > running tests with @ignore. Good to know, thanks! Updated webrev: http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/webrev.02/ HG export: http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/JDK-8061305.jdk8.export.patch How does it look? > Let me know if you need me to sponsor the change. Yes, once approved for JDK 8u I'd need a sponsor to get this pushed. I'll let you know once it's ready and approved. Thanks, Severin > -- Jon > > > > On 06/19/2018 05:01 AM, Severin Gehwolf wrote: > > Hi, > > > > Could I please get a review of this backport of JDK-8061305 for JDK > > 8u? > > JDK-8061305 is in JDK 9+ for a long time now and we've been using > > this > > patch in Fedora for years. The actual patch to > > VisibleMemberMap.java > > hasn't changed (post-path-unshuffeling) from JDK 9, but the tests > > went > > through great lengths of refactoring in later JDK versions. Thus, > > I've > > gone down the route of writing a minimal test case for JDK 8 using > > the > > old-style testing. > > > > Bug: https://bugs.openjdk.java.net/browse/JDK-8061305 > > webrev: http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/we > > brev.01/ > > > > Testing: New regression test, > > test/com/sun/javadoc/ > > Before: passed: 139; failed: 1; error: 2 > > After: Test results: passed: 140; error: 2 > > > > The tests in error are marked with @ignore. Thoughts? > > > > Thanks, > > Severin > > From jonathan.gibbons at oracle.com Mon Jun 25 16:54:27 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 25 Jun 2018 09:54:27 -0700 Subject: RFR: JDK-JDK-8187288 : bad (no) wrapping for modifier and type column In-Reply-To: <6d1989be-ea64-e233-dfb0-aba768fc8915@oracle.com> References: <6d1989be-ea64-e233-dfb0-aba768fc8915@oracle.com> Message-ID: <4d013454-c214-f9c5-5ab2-1cb3125d2c74@oracle.com> On 6/15/18 5:42 AM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8187288 > webrev: http://cr.openjdk.java.net/~pmuthuswamy/8187288/webrev.00/ > > Thanks, > Priya This fix has the problem that you have an "inappropriate" import in the toolkit package for a class from the formats.html package.? The intended design is that the toolkit packages are "format neutral" and do not depend on any specific output format. Although we don't use that feature today, in the past it has been used to generate alternate output files, like FrameMaker etc. Although it need not be part of this work, we should revive the idea of having tests that verify that imports follow the intended constraints.? We did this with some amount of scripting during the doclet conversion; I'll see what can be done in a more formal manner. -- Jon From sgehwolf at redhat.com Tue Jun 26 07:57:18 2018 From: sgehwolf at redhat.com (Severin Gehwolf) Date: Tue, 26 Jun 2018 09:57:18 +0200 Subject: [8u] RFR: 8061305: Javadoc crashes when method name ends with "Property" In-Reply-To: References: <5B2D6B37.20308@oracle.com> Message-ID: Hi Jon, On Mon, 2018-06-25 at 11:02 +0200, Severin Gehwolf wrote: > Updated webrev: > http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/webrev.02/ > HG export: > http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/JDK-8061305.jdk8.export.patch > > How does it look? > > > Let me know if you need me to sponsor the change. > > Yes, once approved for JDK 8u I'd need a sponsor to get this pushed. > I'll let you know once it's ready and approved. Rob approved the backport for 8u: http://mail.openjdk.java.net/pipermail/jdk8u-dev/2018-June/007576.html If you could sponsor pushing this change to 8u, I'd appreciate it. Thanks, Severin From priya.lakshmi.muthuswamy at oracle.com Tue Jun 26 15:47:35 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Tue, 26 Jun 2018 21:17:35 +0530 Subject: RFR: JDK-JDK-8187288 : bad (no) wrapping for modifier and type column In-Reply-To: <4d013454-c214-f9c5-5ab2-1cb3125d2c74@oracle.com> References: <6d1989be-ea64-e233-dfb0-aba768fc8915@oracle.com> <4d013454-c214-f9c5-5ab2-1cb3125d2c74@oracle.com> Message-ID: <083a39fd-9478-e021-12ea-4cb0b1fb72af@oracle.com> Thanks Jon for the comments. Updated webrev : http://cr.openjdk.java.net/~pmuthuswamy/8187288/webrev.01/ Thanks, Priya On 6/25/2018 10:24 PM, Jonathan Gibbons wrote: > > > On 6/15/18 5:42 AM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the fix for >> https://bugs.openjdk.java.net/browse/JDK-8187288 >> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8187288/webrev.00/ >> >> Thanks, >> Priya > This fix has the problem that you have an "inappropriate" import in > the toolkit > package for a class from the formats.html package.? The intended > design is that > the toolkit packages are "format neutral" and do not depend on any > specific > output format. Although we don't use that feature today, in the past > it has been > used to generate alternate output files, like FrameMaker etc. > > Although it need not be part of this work, we should revive the idea > of having > tests that verify that imports follow the intended constraints. We did > this with > some amount of scripting during the doclet conversion; I'll see what > can be > done in a more formal manner. > > -- Jon > > From jonathan.gibbons at oracle.com Wed Jun 27 01:17:52 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 26 Jun 2018 18:17:52 -0700 Subject: RFR: JDK-JDK-8187288 : bad (no) wrapping for modifier and type column In-Reply-To: <083a39fd-9478-e021-12ea-4cb0b1fb72af@oracle.com> References: <6d1989be-ea64-e233-dfb0-aba768fc8915@oracle.com> <4d013454-c214-f9c5-5ab2-1cb3125d2c74@oracle.com> <083a39fd-9478-e021-12ea-4cb0b1fb72af@oracle.com> Message-ID: <5B32E5C0.2020403@oracle.com> Priya, An alternative would have been to leave most of getTypeParameterLinks in place and then introduce new method get get the zero-width spac e, but this is OK. The webrev is hard to read, because it looks like the "webrev" utility is not handling the entity correctly. However, the patch file looks OK. In the stylesheet file, line 825, put a space between "pre" and "{". No need for a re-review for just that change. -- Jon On 06/26/2018 08:47 AM, Priya Lakshmi Muthuswamy wrote: > Thanks Jon for the comments. > Updated webrev : > http://cr.openjdk.java.net/~pmuthuswamy/8187288/webrev.01/ > > Thanks, > Priya > > On 6/25/2018 10:24 PM, Jonathan Gibbons wrote: >> >> >> On 6/15/18 5:42 AM, Priya Lakshmi Muthuswamy wrote: >>> Hi, >>> >>> Kindly review the fix for >>> https://bugs.openjdk.java.net/browse/JDK-8187288 >>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8187288/webrev.00/ >>> >>> Thanks, >>> Priya >> This fix has the problem that you have an "inappropriate" import in >> the toolkit >> package for a class from the formats.html package. The intended >> design is that >> the toolkit packages are "format neutral" and do not depend on any >> specific >> output format. Although we don't use that feature today, in the past >> it has been >> used to generate alternate output files, like FrameMaker etc. >> >> Although it need not be part of this work, we should revive the idea >> of having >> tests that verify that imports follow the intended constraints. We >> did this with >> some amount of scripting during the doclet conversion; I'll see what >> can be >> done in a more formal manner. >> >> -- Jon >> >> > From hannes.wallnoefer at oracle.com Wed Jun 27 15:57:48 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 27 Jun 2018 17:57:48 +0200 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <5B2D6886.6050801@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> Message-ID: Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ Thanks, Hannes > Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : > > While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. > > -- Jon > > > On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >> Thanks for the review, Jon. >> >> I?ve uploaded a new webrev to address the issues you brought up: >> >> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >> >> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >> >> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >> >> Hannes >> >> >>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>> >>> Minor issues to address: >>> >>> HtmlConfiguration, 397, 406: >>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>> >>> SearchIndexItem >>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>> >>> Style issue: >>> >>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>> >>> -- Jon >>> >>> >>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>> >>>> The sorting order for types, members, and search tags is not changed. >>>> >>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>> >>>> Please review: >>>> >>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>> >>>> Thanks, >>>> Hannes > From jonathan.gibbons at oracle.com Wed Jun 27 16:05:33 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 09:05:33 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> Message-ID: <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> Hannes, Can you explain more what you mean by ... "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." -- Jon On 6/27/18 8:57 AM, Hannes Walln?fer wrote: > Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. > > http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ > > Thanks, > Hannes > > >> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >> >> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >> >> -- Jon >> >> >> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>> Thanks for the review, Jon. >>> >>> I?ve uploaded a new webrev to address the issues you brought up: >>> >>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>> >>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>> >>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>> >>> Hannes >>> >>> >>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>> >>>> Minor issues to address: >>>> >>>> HtmlConfiguration, 397, 406: >>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>> >>>> SearchIndexItem >>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>> >>>> Style issue: >>>> >>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>> >>>> -- Jon >>>> >>>> >>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>> >>>>> The sorting order for types, members, and search tags is not changed. >>>>> >>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>> >>>>> Please review: >>>>> >>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>> >>>>> Thanks, >>>>> Hannes From hannes.wallnoefer at oracle.com Wed Jun 27 16:24:31 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 27 Jun 2018 18:24:31 +0200 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> Message-ID: When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. Hannes > Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : > > Hannes, > > Can you explain more what you mean by ... > > "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." > > -- Jon > > > On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >> >> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >> >> Thanks, >> Hannes >> >> >>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>> >>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>> >>> -- Jon >>> >>> >>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>> Thanks for the review, Jon. >>>> >>>> I?ve uploaded a new webrev to address the issues you brought up: >>>> >>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>> >>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>> >>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>> >>>> Hannes >>>> >>>> >>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>> >>>>> Minor issues to address: >>>>> >>>>> HtmlConfiguration, 397, 406: >>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>> >>>>> SearchIndexItem >>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>> >>>>> Style issue: >>>>> >>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>> >>>>> -- Jon >>>>> >>>>> >>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>> >>>>>> The sorting order for types, members, and search tags is not changed. >>>>>> >>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>> >>>>>> Please review: >>>>>> >>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>> >>>>>> Thanks, >>>>>> Hannes > From jonathan.gibbons at oracle.com Wed Jun 27 17:20:26 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 10:20:26 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> Message-ID: This seems like flawed reasoning.? We should not have an inconsistent policy just because it affects a particular use case and/or test. Either we believe in using collation for sorting the index entries, or we don't. -- Jon On 6/27/18 9:24 AM, Hannes Walln?fer wrote: > When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. > > It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. > > Hannes > >> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : >> >> Hannes, >> >> Can you explain more what you mean by ... >> >> "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." >> >> -- Jon >> >> >> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >>> >>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>> >>> Thanks, >>> Hannes >>> >>> >>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>>> >>>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>>> >>>> -- Jon >>>> >>>> >>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>> Thanks for the review, Jon. >>>>> >>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>> >>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>> >>>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>>> >>>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>>> >>>>> Hannes >>>>> >>>>> >>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>>> >>>>>> Minor issues to address: >>>>>> >>>>>> HtmlConfiguration, 397, 406: >>>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>>> >>>>>> SearchIndexItem >>>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>>> >>>>>> Style issue: >>>>>> >>>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>>> >>>>>> -- Jon >>>>>> >>>>>> >>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>>> >>>>>>> The sorting order for types, members, and search tags is not changed. >>>>>>> >>>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>>> >>>>>>> Please review: >>>>>>> >>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>> >>>>>>> Thanks, >>>>>>> Hannes From hannes.wallnoefer at oracle.com Wed Jun 27 18:36:10 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 27 Jun 2018 20:36:10 +0200 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> Message-ID: <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> Here?s a new webrev with collator applied to all search results (search tags now use generic comparator, specific search tag comparator is removed). The search tag test has been updated to expect the new order. http://cr.openjdk.java.net/~hannesw/8190876/webrev.03/ Hannes > Am 27.06.2018 um 19:20 schrieb Jonathan Gibbons : > > This seems like flawed reasoning. We should not have an inconsistent policy just because it affects a particular use case and/or test. > > Either we believe in using collation for sorting the index entries, or we don't. > > -- Jon > > > On 6/27/18 9:24 AM, Hannes Walln?fer wrote: >> When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. >> >> It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. >> >> Hannes >> >>> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : >>> >>> Hannes, >>> >>> Can you explain more what you mean by ... >>> >>> "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." >>> >>> -- Jon >>> >>> >>> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>>> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >>>> >>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>>> >>>> Thanks, >>>> Hannes >>>> >>>> >>>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>>>> >>>>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>>>> >>>>> -- Jon >>>>> >>>>> >>>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>>> Thanks for the review, Jon. >>>>>> >>>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>>> >>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>>> >>>>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>>>> >>>>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>>>> >>>>>> Hannes >>>>>> >>>>>> >>>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>>>> >>>>>>> Minor issues to address: >>>>>>> >>>>>>> HtmlConfiguration, 397, 406: >>>>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>>>> >>>>>>> SearchIndexItem >>>>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>>>> >>>>>>> Style issue: >>>>>>> >>>>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>>>> >>>>>>> -- Jon >>>>>>> >>>>>>> >>>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>>>> >>>>>>>> The sorting order for types, members, and search tags is not changed. >>>>>>>> >>>>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>>>> >>>>>>>> Please review: >>>>>>>> >>>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>>> >>>>>>>> Thanks, >>>>>>>> Hannes > From jonathan.gibbons at oracle.com Wed Jun 27 18:49:46 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 11:49:46 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> Message-ID: <5B33DC4A.3060903@oracle.com> Thanks, I'll check this shortly. -- Jon On 06/27/2018 11:36 AM, Hannes Walln?fer wrote: > Here?s a new webrev with collator applied to all search results (search tags now use generic comparator, specific search tag comparator is removed). The search tag test has been updated to expect the new order. > > http://cr.openjdk.java.net/~hannesw/8190876/webrev.03/ > > Hannes > > >> Am 27.06.2018 um 19:20 schrieb Jonathan Gibbons : >> >> This seems like flawed reasoning. We should not have an inconsistent policy just because it affects a particular use case and/or test. >> >> Either we believe in using collation for sorting the index entries, or we don't. >> >> -- Jon >> >> >> On 6/27/18 9:24 AM, Hannes Walln?fer wrote: >>> When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. >>> >>> It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. >>> >>> Hannes >>> >>>> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : >>>> >>>> Hannes, >>>> >>>> Can you explain more what you mean by ... >>>> >>>> "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." >>>> >>>> -- Jon >>>> >>>> >>>> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>>>> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >>>>> >>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>>>> >>>>> Thanks, >>>>> Hannes >>>>> >>>>> >>>>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>>>>> >>>>>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>>>>> >>>>>> -- Jon >>>>>> >>>>>> >>>>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>>>> Thanks for the review, Jon. >>>>>>> >>>>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>>>> >>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>>>> >>>>>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>>>>> >>>>>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>>>>> >>>>>>> Hannes >>>>>>> >>>>>>> >>>>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>>>>> >>>>>>>> Minor issues to address: >>>>>>>> >>>>>>>> HtmlConfiguration, 397, 406: >>>>>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>>>>> >>>>>>>> SearchIndexItem >>>>>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>>>>> >>>>>>>> Style issue: >>>>>>>> >>>>>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>>>>> >>>>>>>> -- Jon >>>>>>>> >>>>>>>> >>>>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>>>>> >>>>>>>>> The sorting order for types, members, and search tags is not changed. >>>>>>>>> >>>>>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>>>>> >>>>>>>>> Please review: >>>>>>>>> >>>>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>>>> >>>>>>>>> Thanks, >>>>>>>>> Hannes From jonathan.gibbons at oracle.com Wed Jun 27 20:12:00 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 13:12:00 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> Message-ID: <5B33EF90.9070801@oracle.com> Utils.java The secondary comparisons, on lines 2093, 2113 still use String.compareTo instead of compareStrings. -- Jon On 06/27/2018 11:36 AM, Hannes Walln?fer wrote: > Here?s a new webrev with collator applied to all search results (search tags now use generic comparator, specific search tag comparator is removed). The search tag test has been updated to expect the new order. > > http://cr.openjdk.java.net/~hannesw/8190876/webrev.03/ > > Hannes > > >> Am 27.06.2018 um 19:20 schrieb Jonathan Gibbons : >> >> This seems like flawed reasoning. We should not have an inconsistent policy just because it affects a particular use case and/or test. >> >> Either we believe in using collation for sorting the index entries, or we don't. >> >> -- Jon >> >> >> On 6/27/18 9:24 AM, Hannes Walln?fer wrote: >>> When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. >>> >>> It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. >>> >>> Hannes >>> >>>> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : >>>> >>>> Hannes, >>>> >>>> Can you explain more what you mean by ... >>>> >>>> "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." >>>> >>>> -- Jon >>>> >>>> >>>> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>>>> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >>>>> >>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>>>> >>>>> Thanks, >>>>> Hannes >>>>> >>>>> >>>>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>>>>> >>>>>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>>>>> >>>>>> -- Jon >>>>>> >>>>>> >>>>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>>>> Thanks for the review, Jon. >>>>>>> >>>>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>>>> >>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>>>> >>>>>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>>>>> >>>>>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>>>>> >>>>>>> Hannes >>>>>>> >>>>>>> >>>>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>>>>> >>>>>>>> Minor issues to address: >>>>>>>> >>>>>>>> HtmlConfiguration, 397, 406: >>>>>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>>>>> >>>>>>>> SearchIndexItem >>>>>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>>>>> >>>>>>>> Style issue: >>>>>>>> >>>>>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>>>>> >>>>>>>> -- Jon >>>>>>>> >>>>>>>> >>>>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>>>>> >>>>>>>>> The sorting order for types, members, and search tags is not changed. >>>>>>>>> >>>>>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>>>>> >>>>>>>>> Please review: >>>>>>>>> >>>>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>>>> >>>>>>>>> Thanks, >>>>>>>>> Hannes From hannes.wallnoefer at oracle.com Wed Jun 27 20:42:25 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 27 Jun 2018 22:42:25 +0200 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <5B33EF90.9070801@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> <5B33EF90.9070801@oracle.com> Message-ID: Am 27.06.2018 um 22:12 schrieb Jonathan Gibbons : > > Utils.java > > The secondary comparisons, on lines 2093, 2113 still use String.compareTo instead of compareStrings. > The reason is that TreeSet requires the Comparator to be consistent with equals, i.e. if compare returns 0 for any two of them, TreeSet will consider them as equal and discard one of them. So the reason for the secondary comparison is not just to have consistent order, but (maybe more importantly) avoid losing items that happen to have the same label or name. Also, the toString representation is not what is displayed to the user, so using collation for ordering may not have the expected result. Hannes > -- Jon > > On 06/27/2018 11:36 AM, Hannes Walln?fer wrote: >> Here?s a new webrev with collator applied to all search results (search tags now use generic comparator, specific search tag comparator is removed). The search tag test has been updated to expect the new order. >> >> http://cr.openjdk.java.net/~hannesw/8190876/webrev.03/ >> >> Hannes >> >> >>> Am 27.06.2018 um 19:20 schrieb Jonathan Gibbons : >>> >>> This seems like flawed reasoning. We should not have an inconsistent policy just because it affects a particular use case and/or test. >>> >>> Either we believe in using collation for sorting the index entries, or we don't. >>> >>> -- Jon >>> >>> >>> On 6/27/18 9:24 AM, Hannes Walln?fer wrote: >>>> When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. >>>> >>>> It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. >>>> >>>> Hannes >>>> >>>>> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : >>>>> >>>>> Hannes, >>>>> >>>>> Can you explain more what you mean by ... >>>>> >>>>> "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." >>>>> >>>>> -- Jon >>>>> >>>>> >>>>> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>>>>> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >>>>>> >>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>>>>> >>>>>> Thanks, >>>>>> Hannes >>>>>> >>>>>> >>>>>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>>>>>> >>>>>>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>>>>>> >>>>>>> -- Jon >>>>>>> >>>>>>> >>>>>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>>>>> Thanks for the review, Jon. >>>>>>>> >>>>>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>>>>> >>>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>>>>> >>>>>>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>>>>>> >>>>>>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>>>>>> >>>>>>>> Hannes >>>>>>>> >>>>>>>> >>>>>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>>>>>> >>>>>>>>> Minor issues to address: >>>>>>>>> >>>>>>>>> HtmlConfiguration, 397, 406: >>>>>>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>>>>>> >>>>>>>>> SearchIndexItem >>>>>>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>>>>>> >>>>>>>>> Style issue: >>>>>>>>> >>>>>>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>>>>>> >>>>>>>>> -- Jon >>>>>>>>> >>>>>>>>> >>>>>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>>>>>> >>>>>>>>>> The sorting order for types, members, and search tags is not changed. >>>>>>>>>> >>>>>>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>>>>>> >>>>>>>>>> Please review: >>>>>>>>>> >>>>>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>>>>> >>>>>>>>>> Thanks, >>>>>>>>>> Hannes > From jonathan.gibbons at oracle.com Wed Jun 27 20:49:00 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 13:49:00 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> <5B33EF90.9070801@oracle.com> Message-ID: <08c17f06-9931-b7a4-dddd-c2198629a091@oracle.com> OK, Please add a comment to that effect in the code, so we don't lose that info. -- Jon On 6/27/18 1:42 PM, Hannes Walln?fer wrote: > Am 27.06.2018 um 22:12 schrieb Jonathan Gibbons : >> Utils.java >> >> The secondary comparisons, on lines 2093, 2113 still use String.compareTo instead of compareStrings. >> > The reason is that TreeSet requires the Comparator to be consistent with equals, i.e. if compare returns 0 for any two of them, TreeSet will consider them as equal and discard one of them. > > So the reason for the secondary comparison is not just to have consistent order, but (maybe more importantly) avoid losing items that happen to have the same label or name. > > Also, the toString representation is not what is displayed to the user, so using collation for ordering may not have the expected result. > > Hannes > > >> -- Jon >> >> On 06/27/2018 11:36 AM, Hannes Walln?fer wrote: >>> Here?s a new webrev with collator applied to all search results (search tags now use generic comparator, specific search tag comparator is removed). The search tag test has been updated to expect the new order. >>> >>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.03/ >>> >>> Hannes >>> >>> >>>> Am 27.06.2018 um 19:20 schrieb Jonathan Gibbons : >>>> >>>> This seems like flawed reasoning. We should not have an inconsistent policy just because it affects a particular use case and/or test. >>>> >>>> Either we believe in using collation for sorting the index entries, or we don't. >>>> >>>> -- Jon >>>> >>>> >>>> On 6/27/18 9:24 AM, Hannes Walln?fer wrote: >>>>> When searching for ?jav?, Search Tags contains ?Java Collections Framework? followed by various java* command line tools. When using collation, the first item is ?javac?, followed by ?Java Collections Framework? and then the remaining java* tools. >>>>> >>>>> It just looks strange and it causes tests to fail, so I opted for keeping search tag order as it is. >>>>> >>>>> Hannes >>>>> >>>>>> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons : >>>>>> >>>>>> Hannes, >>>>>> >>>>>> Can you explain more what you mean by ... >>>>>> >>>>>> "except search tags, where collation causes frameworks and commands to be mixed up and tests to fail." >>>>>> >>>>>> -- Jon >>>>>> >>>>>> >>>>>> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>>>>>> Updated webrev with comparators moved to Utils. All index items use collation for primary comparison except search tags, where collation causes frameworks and commands to be mixed up and tests to fail. Comparators for index collections are created in HtmlConfiguration.initConfiguration, I think Locale should be set by then. >>>>>>> >>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>>>>>> >>>>>>> Thanks, >>>>>>> Hannes >>>>>>> >>>>>>> >>>>>>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons : >>>>>>>> >>>>>>>> While I agree that Utils is not a great place for the comparators, I will note that the comparison routines there are better than the "simple" ones you have placed in SearchIndexItem. In particular, the existing comparison code in Utils uses java.text.Collator to provide locale-sensitive comparison, which is conceptually more correct than your simple comparison of the upper-cased strings. >>>>>>>> >>>>>>>> -- Jon >>>>>>>> >>>>>>>> >>>>>>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>>>>>> Thanks for the review, Jon. >>>>>>>>> >>>>>>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>>>>>> >>>>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>>>>>> >>>>>>>>> Moving the index item comparators up to Utils didn?t feel right, so I made them static and moved them to SearchIndexItem.java, which feels more appropriate to me. The generic one that is used multiple times is now a singleton. >>>>>>>>> >>>>>>>>> I also forgot to update SearchTest.java for the changes in search.js file, that is included in the new webrev. >>>>>>>>> >>>>>>>>> Hannes >>>>>>>>> >>>>>>>>> >>>>>>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons : >>>>>>>>>> >>>>>>>>>> Minor issues to address: >>>>>>>>>> >>>>>>>>>> HtmlConfiguration, 397, 406: >>>>>>>>>> You're using .toUpperCase() which depends on the Locale. The convention in javadoc is to use Utils.to{Lower,Upper}Case(String), which forces the en-US locale (to avoid the Turkish-i problem). There is an equivalent convention in javac as well. >>>>>>>>>> >>>>>>>>>> SearchIndexItem >>>>>>>>>> If I understand the code correctly, "NestedName" is not the correct term to be using. I think you're trying to get the "simple name". Nesting is a different concept, as in, "nested classes". In a better/future world, SearchIndexItem should contain an Element (not should not always be only string based) and once you have an Element, you can easily get the simple name. >>>>>>>>>> >>>>>>>>>> Style issue: >>>>>>>>>> >>>>>>>>>> Although not wrong, it seems less than ideal to have functions creating and returning equal instances of the comparators, as compared to having singleton instances stored as needed. But then, it's also weird to have these search indexes stored in HtmlConfiguration, as compared to a search-related class. In addition, Utils has many comparators, so you arguably should not be adding more comparators here in HtmlConfiguration. (Not that I like the overuse of the Utils bucket.) >>>>>>>>>> >>>>>>>>>> -- Jon >>>>>>>>>> >>>>>>>>>> >>>>>>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>>>>>> This changes sorting order of packages and modules in the search box from last name segment to whole package or module name, respectively. Apart from fixing the observed issue that leads to more intuitive listings as package and module names are hierarchic by nature. >>>>>>>>>>> >>>>>>>>>>> The sorting order for types, members, and search tags is not changed. >>>>>>>>>>> >>>>>>>>>>> The patch also moves sorting from client side JavaScript to Java, speeding up rendering of search results by at over 2x. It also provides the benefit of secondary order, so members and types with the same name and signature are now ordered by package name, whereas their order was undefined before. >>>>>>>>>>> >>>>>>>>>>> Please review: >>>>>>>>>>> >>>>>>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>>>>>> >>>>>>>>>>> Thanks, >>>>>>>>>>> Hannes From jonathan.gibbons at oracle.com Wed Jun 27 20:50:49 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 13:50:49 -0700 Subject: RFR: 8190876: javadoc search on "java.se" shows "java.se" the last one among other modules In-Reply-To: <08c17f06-9931-b7a4-dddd-c2198629a091@oracle.com> References: <63B2212B-2020-42B1-90A3-117538A8E241@oracle.com> <5B27F8AB.9020705@oracle.com> <2EEF8B97-4992-4088-B68D-DD92BA081738@oracle.com> <5B2D6886.6050801@oracle.com> <12b27e74-c13b-e2ba-f323-8dfdd1398f30@oracle.com> <11C57D8D-53CE-47B1-8D83-35C79DE8FBEB@oracle.com> <5B33EF90.9070801@oracle.com> <08c17f06-9931-b7a4-dddd-c2198629a091@oracle.com> Message-ID: <821d2292-71f7-2977-1c62-1f81ec80a296@oracle.com> If you just add a comment explaining the secondary comparison, you don't need another round of review. -- Jon On 6/27/18 1:49 PM, Jonathan Gibbons wrote: > OK, > > Please add a comment to that effect in the code, so we don't lose that > info. > > -- Jon > > > On 6/27/18 1:42 PM, Hannes Walln?fer wrote: >> Am 27.06.2018 um 22:12 schrieb Jonathan Gibbons >> : >>> Utils.java >>> >>> The secondary comparisons, on lines 2093, 2113 still use >>> String.compareTo instead of compareStrings. >>> >> The reason is that TreeSet requires the Comparator to be consistent >> with equals, i.e. if compare returns 0 for any two of them, TreeSet >> will consider them as equal and discard one of them. >> >> So the reason for the secondary comparison is not just to have >> consistent order, but (maybe more importantly) avoid losing items >> that happen to have the same label or name. >> >> Also, the toString representation is not what is displayed to the >> user, so using collation for ordering may not have the expected result. >> >> Hannes >> >> >>> -- Jon >>> >>> On 06/27/2018 11:36 AM, Hannes Walln?fer wrote: >>>> Here?s a new webrev with collator applied to all search results >>>> (search tags now use generic comparator, specific search tag >>>> comparator is removed). The search tag test has been updated to >>>> expect the new order. >>>> >>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.03/ >>>> >>>> Hannes >>>> >>>>> Am 27.06.2018 um 19:20 schrieb Jonathan Gibbons >>>>> : >>>>> >>>>> This seems like flawed reasoning.? We should not have an >>>>> inconsistent policy just because it affects a particular use case >>>>> and/or test. >>>>> >>>>> Either we believe in using collation for sorting the index >>>>> entries, or we don't. >>>>> >>>>> -- Jon >>>>> >>>>> >>>>> On 6/27/18 9:24 AM, Hannes Walln?fer wrote: >>>>>> When searching for ?jav?, Search Tags contains ?Java Collections >>>>>> Framework? followed by various java* command line tools. When >>>>>> using collation, the first item is ?javac?, followed by ?Java >>>>>> Collections Framework? and then the remaining java* tools. >>>>>> >>>>>> It just looks strange and it causes tests to fail, so I opted for >>>>>> keeping search tag order as it is. >>>>>> >>>>>> Hannes >>>>>> >>>>>>> Am 27.06.2018 um 18:05 schrieb Jonathan Gibbons >>>>>>> : >>>>>>> >>>>>>> Hannes, >>>>>>> >>>>>>> Can you explain more what you mean by ... >>>>>>> >>>>>>> "except search tags, where collation causes frameworks and >>>>>>> commands to be mixed up and tests to fail." >>>>>>> >>>>>>> -- Jon >>>>>>> >>>>>>> >>>>>>> On 6/27/18 8:57 AM, Hannes Walln?fer wrote: >>>>>>>> Updated webrev with comparators moved to Utils. All index items >>>>>>>> use collation for primary comparison except search tags, where >>>>>>>> collation causes frameworks and commands to be mixed up and >>>>>>>> tests to fail. Comparators for index collections are created in >>>>>>>> HtmlConfiguration.initConfiguration, I think Locale should be >>>>>>>> set by then. >>>>>>>> >>>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.02/ >>>>>>>> >>>>>>>> Thanks, >>>>>>>> Hannes >>>>>>>> >>>>>>>> >>>>>>>>> Am 22.06.2018 um 23:22 schrieb Jonathan Gibbons >>>>>>>>> : >>>>>>>>> >>>>>>>>> While I agree that Utils is not a great place for the >>>>>>>>> comparators, I will note that the comparison routines there >>>>>>>>> are better than the "simple" ones you have placed in >>>>>>>>> SearchIndexItem. In particular, the existing comparison code >>>>>>>>> in Utils uses java.text.Collator to provide locale-sensitive >>>>>>>>> comparison, which is conceptually more correct than your >>>>>>>>> simple comparison of the upper-cased strings. >>>>>>>>> >>>>>>>>> -- Jon >>>>>>>>> >>>>>>>>> >>>>>>>>> On 06/19/2018 03:03 AM, Hannes Walln?fer wrote: >>>>>>>>>> Thanks for the review, Jon. >>>>>>>>>> >>>>>>>>>> I?ve uploaded a new webrev to address the issues you brought up: >>>>>>>>>> >>>>>>>>>> http://cr.openjdk.java.net/~hannesw/8190876/webrev.01/ >>>>>>>>>> >>>>>>>>>> Moving the index item comparators up to Utils didn?t feel >>>>>>>>>> right, so I made them static and moved them to >>>>>>>>>> SearchIndexItem.java, which feels more appropriate to me. The >>>>>>>>>> generic one that is used multiple times is now a singleton. >>>>>>>>>> >>>>>>>>>> I also forgot to update SearchTest.java for the changes in >>>>>>>>>> search.js file, that is included in the new webrev. >>>>>>>>>> >>>>>>>>>> Hannes >>>>>>>>>> >>>>>>>>>> >>>>>>>>>>> Am 18.06.2018 um 20:23 schrieb Jonathan Gibbons >>>>>>>>>>> : >>>>>>>>>>> >>>>>>>>>>> Minor issues to address: >>>>>>>>>>> >>>>>>>>>>> HtmlConfiguration, 397, 406: >>>>>>>>>>> You're using .toUpperCase() which depends on the Locale.? >>>>>>>>>>> The convention in javadoc is to use >>>>>>>>>>> Utils.to{Lower,Upper}Case(String), which forces the en-US >>>>>>>>>>> locale (to avoid the Turkish-i problem). There is an >>>>>>>>>>> equivalent convention in javac as well. >>>>>>>>>>> >>>>>>>>>>> SearchIndexItem >>>>>>>>>>> If I understand the code correctly, "NestedName" is not the >>>>>>>>>>> correct term to be using.? I think you're trying to get the >>>>>>>>>>> "simple name". Nesting is a different concept, as in, >>>>>>>>>>> "nested classes".? In a better/future world, SearchIndexItem >>>>>>>>>>> should contain an Element (not should not always be only >>>>>>>>>>> string based) and once you have an Element, you can easily >>>>>>>>>>> get the simple name. >>>>>>>>>>> >>>>>>>>>>> Style issue: >>>>>>>>>>> >>>>>>>>>>> Although not wrong, it seems less than ideal to have >>>>>>>>>>> functions creating and returning equal instances of the >>>>>>>>>>> comparators, as compared to having singleton instances >>>>>>>>>>> stored as needed. But then, it's also weird to have these >>>>>>>>>>> search indexes stored in HtmlConfiguration, as compared to a >>>>>>>>>>> search-related class.? In addition, Utils has many >>>>>>>>>>> comparators, so you arguably should not be adding more >>>>>>>>>>> comparators here in HtmlConfiguration. (Not that I like the >>>>>>>>>>> overuse of the Utils bucket.) >>>>>>>>>>> >>>>>>>>>>> -- Jon >>>>>>>>>>> >>>>>>>>>>> >>>>>>>>>>> On 06/15/2018 12:43 AM, Hannes Walln?fer wrote: >>>>>>>>>>>> This changes sorting order of packages and modules in the >>>>>>>>>>>> search box from last name segment to whole package or >>>>>>>>>>>> module name, respectively. Apart from fixing the observed >>>>>>>>>>>> issue that leads to more intuitive listings as package and >>>>>>>>>>>> module names are hierarchic by nature. >>>>>>>>>>>> >>>>>>>>>>>> The sorting order for types, members, and search tags is >>>>>>>>>>>> not changed. >>>>>>>>>>>> >>>>>>>>>>>> The patch also moves sorting from client side JavaScript to >>>>>>>>>>>> Java, speeding up rendering of search results by at over >>>>>>>>>>>> 2x. It also provides the benefit of secondary order, so >>>>>>>>>>>> members and types with the same name and signature are now >>>>>>>>>>>> ordered by package name, whereas their order was undefined >>>>>>>>>>>> before. >>>>>>>>>>>> >>>>>>>>>>>> Please review: >>>>>>>>>>>> >>>>>>>>>>>> Webrev: cr.openjdk.java.net/~hannesw/8190876/webrev.00/ >>>>>>>>>>>> Issue: https://bugs.openjdk.java.net/browse/JDK-8190876 >>>>>>>>>>>> >>>>>>>>>>>> Thanks, >>>>>>>>>>>> Hannes > From jonathan.gibbons at oracle.com Wed Jun 27 21:34:23 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 14:34:23 -0700 Subject: [8u] RFR: 8061305: Javadoc crashes when method name ends with "Property" In-Reply-To: References: <5B2D6B37.20308@oracle.com> Message-ID: <7ab81c8e-7213-0e1c-3aca-abea61dc7988@oracle.com> OK -- Jon On 6/26/18 12:57 AM, Severin Gehwolf wrote: > Hi Jon, > > On Mon, 2018-06-25 at 11:02 +0200, Severin Gehwolf wrote: >> Updated webrev: >> http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/webrev.02/ >> HG export: >> http://cr.openjdk.java.net/~sgehwolf/webrevs/JDK-8061305/JDK-8061305.jdk8.export.patch >> >> How does it look? >> >>> Let me know if you need me to sponsor the change. >> Yes, once approved for JDK 8u I'd need a sponsor to get this pushed. >> I'll let you know once it's ready and approved. > Rob approved the backport for 8u: > http://mail.openjdk.java.net/pipermail/jdk8u-dev/2018-June/007576.html > > If you could sponsor pushing this change to 8u, I'd appreciate it. > > Thanks, > Severin From jonathan.gibbons at oracle.com Wed Jun 27 22:36:58 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Wed, 27 Jun 2018 15:36:58 -0700 Subject: RFR: JDK-8202959: Rearrange the top and bottom navigation bar in the javadoc generated pages In-Reply-To: <5B0DBBF2.4040805@oracle.com> References: <5B0DBBF2.4040805@oracle.com> Message-ID: <5B34118A.6040804@oracle.com> On 05/29/2018 01:45 PM, Jonathan Gibbons wrote: > Please review this change to simplify the navigation bar found at the > top and bottom of most pages. > > In the lower part of the navigation bar, the "ALL_CLASSES" link is > removed, and the remaining items are composed in a single line. > > The link for for the list of all classes, and another for the list of > all packages, are now available on the "index" page, found by clicking > on the INDEX link in the upper part of the navigation bar. > > JBS: https://bugs.openjdk.java.net/browse/JDK-8202959 > Webrev: http://cr.openjdk.java.net/~jjg/8187794/webrev.00/index.html > > -- Jon This is a "refresh" of this RFR. The webrev is newly generated against the latest jdk/jdk repo. There were no merge conflicts or other anomalies. I've added before/after screenshots to the JBS issue, and published a copy of the generated JDK API docs. JBS: https://bugs.openjdk.java.net/browse/JDK-8202959 Webrev: http://cr.openjdk.java.net/~jjg/8187794/webrev.01/index.html API: http://cr.openjdk.java.net/~jjg/8187794/api.01/index.html -- Jon