From jonathan.gibbons at oracle.com Tue Nov 13 21:56:28 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 13 Nov 2018 13:56:28 -0800 Subject: CodeTools proposal: doccheck Message-ID: <0f870666-0f42-e8d9-dae3-81f705508b4e@oracle.com> Name: doccheck Summary: A utility to provide a number of checks for HTML files in the JDK documentation for API and related specifications. Proposed by: Jonathan Gibbons Rationale: This utility has been written to provide simple fast, checking for various aspects of the JDK documentation, such as invalid HTML, broken links, bad characters, and so on. It is useful to compare/contrast this with the "doclint" support in javac and javadoc. The following is from the proposed documentation [1] DocCheck vs. DocLint DocLint is a utility built into javac and javadoc that performs some amount of checking of the content of documentation comments. Although there is some overlap in functionality, the two utilities are different and each has its own strengths and weaknesses. * ||DocCheck checks the end result of any generated documentation. This includes content from all sources, such as documentation comments, the standard doclet, user-provided taglets, and content supplied via command-line options. Because it is analyzing complete HTML pages, it can do more complete checks than can DocLint. However, when problems are found in generated pages, it can be harder to track down exactly where the problem needs to be fixed. (This was a major motivation for writing DocLint.) * DocLint checks the content of documentation comments. This makes it very easy to identify the exact position of any issues that may be found. DocLint can also detect some semantic errors in documentation comments that DocCheck cannot detect, such as using an |@return| tag in a method returning |void|, or a |@param| tag describing a non-existent parameter. But by its nature, DocLint cannot report on problems such as missing links, or errors in user-provided custom taglets, or problems in the standard doclet itself. It also cannot reliably detect errors in documentation comments at the boundaries between content in a documentation comment and content generated by a custom taglet. DocLint does not currently check the content of any HTML pages in |doc-files| subdirectories. These files are simply copied to the output directory, along with any other files in such directories. [1] http://cr.openjdk.java.net/~jjg/doccheck/doc/doccheck.html From martinrb at google.com Thu Nov 15 07:16:51 2018 From: martinrb at google.com (Martin Buchholz) Date: Wed, 14 Nov 2018 23:16:51 -0800 Subject: CodeTools proposal: doccheck In-Reply-To: <0f870666-0f42-e8d9-dae3-81f705508b4e@oracle.com> References: <0f870666-0f42-e8d9-dae3-81f705508b4e@oracle.com> Message-ID: Thanks! I was wondering why there were two different tools, and this is an excellent explanation. On Tue, Nov 13, 2018 at 1:56 PM, Jonathan Gibbons < jonathan.gibbons at oracle.com> wrote: > Name: doccheck > > Summary: A utility to provide a number of checks for HTML files in the JDK > documentation for API and related specifications. > > Proposed by: Jonathan Gibbons > > Rationale: > > This utility has been written to provide simple fast, checking for various > aspects of the JDK documentation, such as invalid HTML, broken links, bad > characters, and so on. It is useful to compare/contrast this with the > "doclint" support in javac and javadoc. The following is from the proposed > documentation [1] > > > DocCheck vs. DocLint > > DocLint is a utility built into javac and javadoc that performs some > amount of checking of the content of documentation comments. > Although there is some overlap in functionality, the two utilities > are different and each has its own strengths and weaknesses. > > * > > ||DocCheck checks the end result of any generated documentation. > This includes content from all sources, such as documentation > comments, the standard doclet, user-provided taglets, and > content supplied via command-line options. Because it is > analyzing complete HTML pages, it can do more complete checks > than can DocLint. > > However, when problems are found in generated pages, it can be > harder to track down exactly where the problem needs to be > fixed. (This was a major motivation for writing DocLint.) > > * > > DocLint checks the content of documentation comments. This makes > it very easy to identify the exact position of any issues that > may be found. DocLint can also detect some semantic errors in > documentation comments that DocCheck cannot detect, such as > using an |@return| tag in a method returning |void|, or a > |@param| tag describing a non-existent parameter. > > But by its nature, DocLint cannot report on problems such as > missing links, or errors in user-provided custom taglets, or > problems in the standard doclet itself. It also cannot reliably > detect errors in documentation comments at the boundaries > between content in a documentation comment and content generated > by a custom taglet. > > DocLint does not currently check the content of any HTML pages > in |doc-files| subdirectories. These files are simply copied to > the output directory, along with any other files in such > directories. > > > [1] http://cr.openjdk.java.net/~jjg/doccheck/doc/doccheck.html > > From jonathan.gibbons at oracle.com Fri Nov 16 01:49:46 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 15 Nov 2018 17:49:46 -0800 Subject: CodeTools proposal: doccheck In-Reply-To: References: <0f870666-0f42-e8d9-dae3-81f705508b4e@oracle.com> Message-ID: <40d36afb-10ae-dd22-3201-5196a2f1c32a@oracle.com> :-) Yes, both are useful; DocCheck is more thorough but it can be tedious to map errors back to source code. It's also the case that since we moved to unified documentation, we've temporarily-it-seems-like-forever disabled a lot of the DocLint checks in the build. Overall, the JDK docs are in pretty good shape, so we should look at turning up the DocLint knobs again. -- Jon On 11/14/2018 11:16 PM, Martin Buchholz wrote: > Thanks!? I was wondering why there were two different tools, and this > is an excellent explanation. > > On Tue, Nov 13, 2018 at 1:56 PM, Jonathan Gibbons > > wrote: > > Name: doccheck > > Summary: A utility to provide a number of checks for HTML files in > the JDK documentation for API and related specifications. > > Proposed by: Jonathan Gibbons > > Rationale: > > This utility has been written to provide simple fast, checking for > various aspects of the JDK documentation, such as invalid HTML, > broken links, bad characters, and so on. It is useful to > compare/contrast this with the "doclint" support in javac and > javadoc. The following is from the proposed documentation [1] > > > ? ? ? ?DocCheck vs. DocLint > > ? ?DocLint is a utility built into javac and javadoc that performs > some > ? ?amount of checking of the content of documentation comments. > ? ?Although there is some overlap in functionality, the two utilities > ? ?are different and each has its own strengths and weaknesses. > > ? ? ?* > > ? ? ? ?||DocCheck checks the end result of any generated > documentation. > ? ? ? ?This includes content from all sources, such as documentation > ? ? ? ?comments, the standard doclet, user-provided taglets, and > ? ? ? ?content supplied via command-line options. Because it is > ? ? ? ?analyzing complete HTML pages, it can do more complete checks > ? ? ? ?than can DocLint. > > ? ? ? ?However, when problems are found in generated pages, it can be > ? ? ? ?harder to track down exactly where the problem needs to be > ? ? ? ?fixed. (This was a major motivation for writing DocLint.) > > ? ? ?* > > ? ? ? ?DocLint checks the content of documentation comments. This > makes > ? ? ? ?it very easy to identify the exact position of any issues that > ? ? ? ?may be found. DocLint can also detect some semantic errors in > ? ? ? ?documentation comments that DocCheck cannot detect, such as > ? ? ? ?using an |@return| tag in a method returning |void|, or a > ? ? ? ?|@param| tag describing a non-existent parameter. > > ? ? ? ?But by its nature, DocLint cannot report on problems such as > ? ? ? ?missing links, or errors in user-provided custom taglets, or > ? ? ? ?problems in the standard doclet itself. It also cannot reliably > ? ? ? ?detect errors in documentation comments at the boundaries > ? ? ? ?between content in a documentation comment and content > generated > ? ? ? ?by a custom taglet. > > ? ? ? ?DocLint does not currently check the content of any HTML pages > ? ? ? ?in |doc-files| subdirectories. These files are simply copied to > ? ? ? ?the output directory, along with any other files in such > ? ? ? ?directories. > > > [1] http://cr.openjdk.java.net/~jjg/doccheck/doc/doccheck.html > > > From eric.caspole at oracle.com Tue Nov 20 21:12:19 2018 From: eric.caspole at oracle.com (Eric Caspole) Date: Tue, 20 Nov 2018 16:12:19 -0500 Subject: RFR: Reorganize jmh-jdk-microbenchmarks for version specific directories Message-ID: <6cc714d5-de87-692c-47ee-93df82535f51@oracle.com> Hi everybody, Could I have reviews on this modification of the existing project to support JDK version specific microbenchmarks? Only a few new files are added to make a placeholder for micros-jdk9, where I soon plan to add some new ones.? All the existing ones are in now micros-jdk8. This change allows people to continue to easily build on and work with JDK 8 only if desired while allowing for new development. http://cr.openjdk.java.net/~ecaspole/jmh_version_specific/webrev/ Thanks, Eric