From hannes.wallnoefer at oracle.com Tue Dec 4 15:53:20 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Tue, 4 Dec 2018 16:53:20 +0100 Subject: RFR: 8214571: -Xdoclint of array serialField gives "error: array type not allowed here" Message-ID: Please review: Bug: https://bugs.openjdk.java.net/browse/JDK-8214571 Webrev: http://cr.openjdk.java.net/~hannesw/8214571/webrev.00/ I changed the handling of array types in reference tags from causing an error to just generating a link to the element type. I only updated the existing tests, should I add a test specifically for @serialField as well? Thanks, Hannes From jonathan.gibbons at oracle.com Tue Dec 4 15:59:29 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Tue, 4 Dec 2018 07:59:29 -0800 Subject: RFR: 8214571: -Xdoclint of array serialField gives "error: array type not allowed here" In-Reply-To: References: Message-ID: <3fa867b7-4228-1723-da53-7f4136004863@oracle.com> On 12/4/18 7:53 AM, Hannes Walln?fer wrote: > Please review: > > Bug: https://bugs.openjdk.java.net/browse/JDK-8214571 > Webrev: http://cr.openjdk.java.net/~hannesw/8214571/webrev.00/ > > I changed the handling of array types in reference tags from causing an error to just generating a link to the element type. > > I only updated the existing tests, should I add a test specifically for @serialField as well? > > Thanks, > Hannes Since the regression was on @serialField, I think we should have a test for @serialField.? Let me know if you want help creating the test. -- Jon From priya.lakshmi.muthuswamy at oracle.com Wed Dec 5 11:28:02 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Wed, 5 Dec 2018 16:58:02 +0530 Subject: RFR: 8214856 : Errors with JSZip in web console after upgrade to 3.1.5 Message-ID: Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8214856 webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.00/ In JSZip 3.x few api's have changed. Made the changes according to the JSZip upgrade guidelines(https://stuk.github.io/jszip/documentation/upgrade_guide.html). Thanks, Priya From hannes.wallnoefer at oracle.com Wed Dec 5 11:52:45 2018 From: hannes.wallnoefer at oracle.com (Hannes Wallnoefer) Date: Wed, 5 Dec 2018 12:52:45 +0100 Subject: RFR: 8214856 : Errors with JSZip in web console after upgrade to 3.1.5 In-Reply-To: References: Message-ID: <72640cb2-a1b5-fdff-c594-a0be63267ce9@oracle.com> Hi Priya, This is not related directly to your change, but why is the JSUtils.getBinaryContent call nested in a $.get()? Is this just to handle errors and check if the zip file is available? It seems like we fetch the zip file twice when we could just test the error argument in the JSUtils.getBinaryContent? callback as shown here: https://stuk.github.io/jszip/documentation/howto/read_zip.html A minor formatting related issue: the indentation of the closing braces/parentheses looks a bit random. Otherwise +1. Hannes Am 05.12.18 um 12:28 schrieb Priya Lakshmi Muthuswamy: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8214856 > webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.00/ > > In JSZip 3.x few api's have changed. Made the changes according to the > JSZip upgrade > guidelines(https://stuk.github.io/jszip/documentation/upgrade_guide.html). > > Thanks, > Priya > > From hannes.wallnoefer at oracle.com Wed Dec 5 12:03:34 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 5 Dec 2018 13:03:34 +0100 Subject: RFR: 8214856 : Errors with JSZip in web console after upgrade to 3.1.5 In-Reply-To: <72640cb2-a1b5-fdff-c594-a0be63267ce9@oracle.com> References: <72640cb2-a1b5-fdff-c594-a0be63267ce9@oracle.com> Message-ID: Am 05.12.2018 um 12:52 schrieb Hannes Wallnoefer : > > A minor formatting related issue: the indentation of the closing braces/parentheses looks a bit random. More precisely: indentation mixes spaces and tabs. > Otherwise +1. > > Hannes > > Am 05.12.18 um 12:28 schrieb Priya Lakshmi Muthuswamy: >> Hi, >> >> Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8214856 >> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.00/ >> >> In JSZip 3.x few api's have changed. Made the changes according to the JSZip upgrade guidelines(https://stuk.github.io/jszip/documentation/upgrade_guide.html). >> >> Thanks, >> Priya >> >> > From priya.lakshmi.muthuswamy at oracle.com Wed Dec 5 12:44:47 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Wed, 5 Dec 2018 18:14:47 +0530 Subject: RFR: 8214856 : Errors with JSZip in web console after upgrade to 3.1.5 In-Reply-To: References: <72640cb2-a1b5-fdff-c594-a0be63267ce9@oracle.com> Message-ID: <9cbf47bc-9f32-c625-7319-107980962dfc@oracle.com> oops sorry for the tabs. updated webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.01/ Thanks, Priya On 12/5/2018 5:33 PM, Hannes Walln?fer wrote: > Am 05.12.2018 um 12:52 schrieb Hannes Wallnoefer : >> A minor formatting related issue: the indentation of the closing braces/parentheses looks a bit random. > More precisely: indentation mixes spaces and tabs. > > >> Otherwise +1. >> >> Hannes >> >> Am 05.12.18 um 12:28 schrieb Priya Lakshmi Muthuswamy: >>> Hi, >>> >>> Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8214856 >>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.00/ >>> >>> In JSZip 3.x few api's have changed. Made the changes according to the JSZip upgrade guidelines(https://stuk.github.io/jszip/documentation/upgrade_guide.html). >>> >>> Thanks, >>> Priya >>> >>> From hannes.wallnoefer at oracle.com Wed Dec 5 12:57:49 2018 From: hannes.wallnoefer at oracle.com (Hannes Wallnoefer) Date: Wed, 5 Dec 2018 13:57:49 +0100 Subject: RFR: 8214856 : Errors with JSZip in web console after upgrade to 3.1.5 In-Reply-To: <9cbf47bc-9f32-c625-7319-107980962dfc@oracle.com> References: <72640cb2-a1b5-fdff-c594-a0be63267ce9@oracle.com> <9cbf47bc-9f32-c625-7319-107980962dfc@oracle.com> Message-ID: +1 Hannes Am 05.12.18 um 13:44 schrieb Priya Lakshmi Muthuswamy: > oops sorry for the tabs. > > updated webrev : > http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.01/ > > Thanks, > Priya > > On 12/5/2018 5:33 PM, Hannes Walln?fer wrote: >> Am 05.12.2018 um 12:52 schrieb Hannes Wallnoefer >> : >>> A minor formatting related issue: the indentation of the closing >>> braces/parentheses looks a bit random. >> More precisely: indentation mixes spaces and tabs. >> >> >>> Otherwise +1. >>> >>> Hannes >>> >>> Am 05.12.18 um 12:28 schrieb Priya Lakshmi Muthuswamy: >>>> Hi, >>>> >>>> Kindly review the fix for >>>> https://bugs.openjdk.java.net/browse/JDK-8214856 >>>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214856/webrev.00/ >>>> >>>> In JSZip 3.x few api's have changed. Made the changes according to >>>> the JSZip upgrade >>>> guidelines(https://stuk.github.io/jszip/documentation/upgrade_guide.html). >>>> >>>> Thanks, >>>> Priya >>>> >>>> From hannes.wallnoefer at oracle.com Wed Dec 5 13:57:35 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 5 Dec 2018 14:57:35 +0100 Subject: RFR: JDK-8214468 : jQuery UI upgrade from 1.11.4 to 1.12.1 In-Reply-To: References: Message-ID: <50EB3B19-AE1F-4E61-9B46-D7589CF86663@oracle.com> Hi Priya, Could it be that you included jQuery UI components that were not included in the previous version and are not used in javadoc? From the changes in the style sheet, it looks like you add CSS definitions that were not there previously for the following components: resizable, selectable, sortable, accordion, button, checkboxradio, controlgroup, datepicker, dialog, progress bar, selectmen, slider, spinner, tabs, tooltip. The generated API docs look good and seem to be working fine. Hannes > Am 29.11.2018 um 09:44 schrieb Priya Lakshmi Muthuswamy : > > Hi, > > Kindly review the changes for jQuery UI upgrade from 1.11.4 to 1.12.1 (https://bugs.openjdk.java.net/browse/JDK-8214468). > > Modifications done: > 1) As per the jQuery UI upgrade guidelines, we need to put wrappers around each menu item > 2) Performance has degraded after updating to 1.12.4. > Jquery UI bug : https://bugs.jqueryui.com/ticket/10050 > After applying suggestions in https://stackoverflow.com/questions/40782638/jquery-autocomplete-performance-going-down-with-each-search, its better. > 3) Default theme has changed. It was smoothness theme in 1.11.4, its now base theme in 1.12.4. > Using the Theme roller, used the smoothness theme and changed the hover color so that its similar to current Javadoc. > > webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.00 > api : http://cr.openjdk.java.net/~pmuthuswamy/8214468/api > > > Thanks, > Priya > From hannes.wallnoefer at oracle.com Wed Dec 5 14:08:04 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 5 Dec 2018 15:08:04 +0100 Subject: RFR: 8214571: -Xdoclint of array serialField gives "error: array type not allowed here" In-Reply-To: <3fa867b7-4228-1723-da53-7f4136004863@oracle.com> References: <3fa867b7-4228-1723-da53-7f4136004863@oracle.com> Message-ID: <1F017A39-82DD-41D3-9E63-DEEA0E12B484@oracle.com> Thanks for the review. I added a @serialField tag to the existing serializedForm test. Also, I removed the private Checker#isArrayType method which isn?t used anymore. New webrev: http://cr.openjdk.java.net/~hannesw/8214571/webrev.01/ Hannes > Am 04.12.2018 um 16:59 schrieb Jonathan Gibbons : > > > On 12/4/18 7:53 AM, Hannes Walln?fer wrote: >> Please review: >> >> Bug: https://bugs.openjdk.java.net/browse/JDK-8214571 >> Webrev: http://cr.openjdk.java.net/~hannesw/8214571/webrev.00/ >> >> I changed the handling of array types in reference tags from causing an error to just generating a link to the element type. >> >> I only updated the existing tests, should I add a test specifically for @serialField as well? >> >> Thanks, >> Hannes > > Since the regression was on @serialField, I think we should have a test for @serialField. Let me know if you want help creating the test. > > -- Jon > From sundararajan.athijegannathan at oracle.com Wed Dec 5 14:33:27 2018 From: sundararajan.athijegannathan at oracle.com (Sundararajan Athijegannathan) Date: Wed, 05 Dec 2018 20:03:27 +0530 Subject: RFR: 8214571: -Xdoclint of array serialField gives "error: array type not allowed here" In-Reply-To: <1F017A39-82DD-41D3-9E63-DEEA0E12B484@oracle.com> References: <3fa867b7-4228-1723-da53-7f4136004863@oracle.com> <1F017A39-82DD-41D3-9E63-DEEA0E12B484@oracle.com> Message-ID: <5C07E1B7.1070800@oracle.com> Looks good. -Sundar On 05/12/18, 7:38 PM, Hannes Walln?fer wrote: > Thanks for the review. > > I added a @serialField tag to the existing serializedForm test. Also, I removed the private Checker#isArrayType method which isn?t used anymore. > > New webrev: > http://cr.openjdk.java.net/~hannesw/8214571/webrev.01/ > > Hannes > >> Am 04.12.2018 um 16:59 schrieb Jonathan Gibbons: >> >> >> On 12/4/18 7:53 AM, Hannes Walln?fer wrote: >>> Please review: >>> >>> Bug: https://bugs.openjdk.java.net/browse/JDK-8214571 >>> Webrev: http://cr.openjdk.java.net/~hannesw/8214571/webrev.00/ >>> >>> I changed the handling of array types in reference tags from causing an error to just generating a link to the element type. >>> >>> I only updated the existing tests, should I add a test specifically for @serialField as well? >>> >>> Thanks, >>> Hannes >> Since the regression was on @serialField, I think we should have a test for @serialField. Let me know if you want help creating the test. >> >> -- Jon >> From priya.lakshmi.muthuswamy at oracle.com Thu Dec 6 08:16:30 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Thu, 6 Dec 2018 13:46:30 +0530 Subject: RFR: JDK-8214468 : jQuery UI upgrade from 1.11.4 to 1.12.1 In-Reply-To: <50EB3B19-AE1F-4E61-9B46-D7589CF86663@oracle.com> References: <50EB3B19-AE1F-4E61-9B46-D7589CF86663@oracle.com> Message-ID: Hi Hannes, Thanks for the review. I had downloaded the jQuery build with default all options enabled. Now i have included only the required components . updated webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.01/ Thanks, Priya On 12/5/2018 7:27 PM, Hannes Walln?fer wrote: > Hi Priya, > > Could it be that you included jQuery UI components that were not included in the previous version and are not used in javadoc? > > From the changes in the style sheet, it looks like you add CSS definitions that were not there previously for the following components: > > resizable, selectable, sortable, accordion, button, checkboxradio, controlgroup, datepicker, dialog, progress bar, selectmen, slider, spinner, tabs, tooltip. > > The generated API docs look good and seem to be working fine. > > Hannes > > >> Am 29.11.2018 um 09:44 schrieb Priya Lakshmi Muthuswamy : >> >> Hi, >> >> Kindly review the changes for jQuery UI upgrade from 1.11.4 to 1.12.1 (https://bugs.openjdk.java.net/browse/JDK-8214468). >> >> Modifications done: >> 1) As per the jQuery UI upgrade guidelines, we need to put wrappers around each menu item >> 2) Performance has degraded after updating to 1.12.4. >> Jquery UI bug : https://bugs.jqueryui.com/ticket/10050 >> After applying suggestions in https://stackoverflow.com/questions/40782638/jquery-autocomplete-performance-going-down-with-each-search, its better. >> 3) Default theme has changed. It was smoothness theme in 1.11.4, its now base theme in 1.12.4. >> Using the Theme roller, used the smoothness theme and changed the hover color so that its similar to current Javadoc. >> >> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.00 >> api : http://cr.openjdk.java.net/~pmuthuswamy/8214468/api >> >> >> Thanks, >> Priya >> From hannes.wallnoefer at oracle.com Thu Dec 6 11:14:54 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Thu, 6 Dec 2018 12:14:54 +0100 Subject: RFR: JDK-8214468 : jQuery UI upgrade from 1.11.4 to 1.12.1 In-Reply-To: References: <50EB3B19-AE1F-4E61-9B46-D7589CF86663@oracle.com> Message-ID: <5C69A1F4-D8CB-4C5D-B990-70E0746B7757@oracle.com> Looks good. Did you make sure generated docs look good as well? Hannes > Am 06.12.2018 um 09:16 schrieb Priya Lakshmi Muthuswamy : > > Hi Hannes, > > Thanks for the review. > I had downloaded the jQuery build with default all options enabled. > Now i have included only the required components . > > updated webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.01/ > > Thanks, > Priya > > On 12/5/2018 7:27 PM, Hannes Walln?fer wrote: >> Hi Priya, >> >> Could it be that you included jQuery UI components that were not included in the previous version and are not used in javadoc? >> >> From the changes in the style sheet, it looks like you add CSS definitions that were not there previously for the following components: >> >> resizable, selectable, sortable, accordion, button, checkboxradio, controlgroup, datepicker, dialog, progress bar, selectmen, slider, spinner, tabs, tooltip. >> >> The generated API docs look good and seem to be working fine. >> >> Hannes >> >> >>> Am 29.11.2018 um 09:44 schrieb Priya Lakshmi Muthuswamy : >>> >>> Hi, >>> >>> Kindly review the changes for jQuery UI upgrade from 1.11.4 to 1.12.1 (https://bugs.openjdk.java.net/browse/JDK-8214468). >>> >>> Modifications done: >>> 1) As per the jQuery UI upgrade guidelines, we need to put wrappers around each menu item >>> 2) Performance has degraded after updating to 1.12.4. >>> Jquery UI bug : https://bugs.jqueryui.com/ticket/10050 >>> After applying suggestions in https://stackoverflow.com/questions/40782638/jquery-autocomplete-performance-going-down-with-each-search, its better. >>> 3) Default theme has changed. It was smoothness theme in 1.11.4, its now base theme in 1.12.4. >>> Using the Theme roller, used the smoothness theme and changed the hover color so that its similar to current Javadoc. >>> >>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.00 >>> api : http://cr.openjdk.java.net/~pmuthuswamy/8214468/api >>> >>> >>> Thanks, >>> Priya >>> From priya.lakshmi.muthuswamy at oracle.com Thu Dec 6 12:49:47 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Thu, 6 Dec 2018 18:19:47 +0530 Subject: RFR: JDK-8214468 : jQuery UI upgrade from 1.11.4 to 1.12.1 In-Reply-To: <5C69A1F4-D8CB-4C5D-B990-70E0746B7757@oracle.com> References: <50EB3B19-AE1F-4E61-9B46-D7589CF86663@oracle.com> <5C69A1F4-D8CB-4C5D-B990-70E0746B7757@oracle.com> Message-ID: <66a39b4a-6265-9456-8c8a-4842357ab609@oracle.com> Yes checked them. uploaded them as well. api : http://cr.openjdk.java.net/~pmuthuswamy/8214468/api_2/ Thanks, Priya On 12/6/2018 4:44 PM, Hannes Walln?fer wrote: > Looks good. Did you make sure generated docs look good as well? > > Hannes > >> Am 06.12.2018 um 09:16 schrieb Priya Lakshmi Muthuswamy : >> >> Hi Hannes, >> >> Thanks for the review. >> I had downloaded the jQuery build with default all options enabled. >> Now i have included only the required components . >> >> updated webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.01/ >> >> Thanks, >> Priya >> >> On 12/5/2018 7:27 PM, Hannes Walln?fer wrote: >>> Hi Priya, >>> >>> Could it be that you included jQuery UI components that were not included in the previous version and are not used in javadoc? >>> >>> From the changes in the style sheet, it looks like you add CSS definitions that were not there previously for the following components: >>> >>> resizable, selectable, sortable, accordion, button, checkboxradio, controlgroup, datepicker, dialog, progress bar, selectmen, slider, spinner, tabs, tooltip. >>> >>> The generated API docs look good and seem to be working fine. >>> >>> Hannes >>> >>> >>>> Am 29.11.2018 um 09:44 schrieb Priya Lakshmi Muthuswamy : >>>> >>>> Hi, >>>> >>>> Kindly review the changes for jQuery UI upgrade from 1.11.4 to 1.12.1 (https://bugs.openjdk.java.net/browse/JDK-8214468). >>>> >>>> Modifications done: >>>> 1) As per the jQuery UI upgrade guidelines, we need to put wrappers around each menu item >>>> 2) Performance has degraded after updating to 1.12.4. >>>> Jquery UI bug : https://bugs.jqueryui.com/ticket/10050 >>>> After applying suggestions in https://stackoverflow.com/questions/40782638/jquery-autocomplete-performance-going-down-with-each-search, its better. >>>> 3) Default theme has changed. It was smoothness theme in 1.11.4, its now base theme in 1.12.4. >>>> Using the Theme roller, used the smoothness theme and changed the hover color so that its similar to current Javadoc. >>>> >>>> webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214468/webrev.00 >>>> api : http://cr.openjdk.java.net/~pmuthuswamy/8214468/api >>>> >>>> >>>> Thanks, >>>> Priya >>>> From jonathan.gibbons at oracle.com Fri Dec 14 22:26:47 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 14 Dec 2018 14:26:47 -0800 Subject: javadoc accessibility: headings Message-ID: <0c089343-d2cf-a417-8b51-8a9f49cd2093@oracle.com> In our ongoing endeavors to improve support in the standard doclet for generating accessible documentation, we need to pay attention to headings.? In this context, "heading" refers to the use of HTML tags

...

in the generated documentation. There are 3 problem areas; all will need to be fixed to address the goal of being able to generate accessible documentation, and provide to accessible JDK documentation. 1. The standard doclet is inconsistent about its use of headings 2. The standard doclet provides little-to-no guidance as to the use of headings in documentation comments 3. Many headings in documentation comments do not follow the best practices for headings in accessible documents The best practices are all to facilitate navigating and reading the page with a screen reader, and can be summarized as follows: * The main heading for a page should be

* There should be just one

per page * Headings should be hierarchical, and without ascending gaps, so

should be followed by

,

should be followed by

or another

, etc.? It is OK to have "missing" headings when starting a new higher level section, so that

may be followed by

, for example; in that case, the

would implicitly end the preceding section at the

level and the one at the

level. For more info, see pages like the following: * https://www.w3.org/TR/WCAG20-TECHS/G141.html * https://www.w3.org/WAI/tutorials/page-structure/headings/ Note: there is no requirement for the standard doclet that all generated documentation *must* be accessible; the desired requirement is just that it *must be possible* to generate accessible documentation. Problems 1. Inconsistent headings The standard doclet generates a number of different kinds of pages, such as for different kinds of declaration, for indexes, for "use" and "tree" pages and so on. Most kinds of pages use

for the main title, but overall, most pages do not use

at all, and start at

These are all the pages for type declarations (classes, interfaces, enums and annotation types.) 2. Little guidance for use of headings Perhaps because the pages for type declarations start at

, there is an informal guideline to "start at

" but this guideline is overly simplistic and often inappropriate. For example, the page for a package or module declaration use

for the title, and so any headings in the documentation comment should start at

. Even worse, because the standard doclet uses headings within the page, any headings in the documentation comments for members of a type need to take those additional levels of headings into account. 3. Bad headings in doc comments Even taking into account the lack of guidance described in the previous paragraph, there are some obvious errors in doc comments. These errors are reported by accessibility checkers, but the needles get lost in the haystack of warnings deriving from the issues arising from the standard doclet itself. Here's one notable error, showing the headings mechanically extracted from a current page in the Java SE documentation. Note that the top-level H1 is missing (that's a problem in the standard doclet), the first H2 and the H3 and H4 that follow are generated by the doclet, but there's a spurious H2 that breaks up the sequence of H4 headings for the methods under the H3 Method detail heading. H1: MISSING * H2: Class DatatypeFactory o H3: Field Summary o H3: Constructor Summary o H3: Method Summary o H3: Methods declared in class?java.lang.Object o H3: Field Detail + H4: DATATYPEFACTORY_PROPERTY + H4: DATATYPEFACTORY_IMPLEMENTATION_CLASS o H3: Constructor Detail + H4: DatatypeFactory o H3: Method Detail + H4: newDefaultInstance + H4: newInstance + H4: newInstance * H2: Tip for Trouble-shooting o H3: MISSING + H4: newDuration + H4: newDuration + H4: newDuration + H4: newDuration + /etc, more H4 deleted/ There's another example in the current JDK API, where there is no H1 at the top of the file (the same as above), but there is an H1 heading later on, in the doc comment for a method. That heading is clearly not the main heading for the page overall. Proposal * Introduce a new mode in the doclet such that all headings directly generated by the standard doclet follow the best practices for hierarchical headings. * Update the "Documentation Comment Specification for the Standard Doclet" [1] to include guidelines for the use of headings in documentation comments in different places, such as top-level declarations, member declarations and stand-alone HTML files. * Update the headings in the JDK API documentation to follow the guidelines for generating hierarchical headings. Using the new mode to generate hierarchical headings may necessitate making changes to documentation comments to achieve the goal. For users that do not want to edit their comments and are happy with the current behavior, the current behavior will continue to be available until any future announcement that it will not be supported. However, the new mode will be the default, because even without editing any comments, the generated docs will be "less bad" than the current behavior. * With the old behavior, all the pages for type declarations have a missing

* With the new behavior and without editing any comments, the only problems in this area will be from those comments that contain explicit headings, which overall, are relatively uncommon. [1] https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html -------------- next part -------------- An HTML attachment was scrubbed... URL: From jonathan.gibbons at oracle.com Mon Dec 17 23:10:54 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Mon, 17 Dec 2018 15:10:54 -0800 Subject: RFR: JDK-8215516: Move JavadocTester to a named package Message-ID: <84f3f7ce-79d3-52e9-489a-97e9dc606b9c@oracle.com> Please review a test-only change to move JavadocTester from the unnamed package to a new, named package. The name of the new package is "javadoc.tester.*". A number of alternatives were considered (javadoc.*, test.javadoc.*, javadoc.test.lib.*, etc)? javadoc.tester.* seemed the least bad. In addition, the location of the library was moved up a level, to allow for more javadoc-related test library classes to be added going forward. Although conceptually simple, this does affect all tests that refer to it. There are up to 4 implications for each test. 1. Update the @library tag for the new location 2. Update the @build tag 3. Add an import for JavadocTester (and cleanup some other library imports, for toolbox classes) 4. For some tests, update the @Test methods to be public Most (but not all) of the preceding changes were done by script and/or IDE. Some outlier cases were done manually, when checking that all tests still passed. One test, TestOrdering.java, required bigger changes, to change static nested classes to inner classes, to utilize access to protected methods. In TestRedirectLinks.java, there is a single-line, unrelated change to disconnect an HttpURLConnection, to help prevent test timeouts. Finally, in JavadocTester itself, the declaration for the @Test type was made public. There is no change to the functionality of any of the affected tests. After from the move, there are no other refactorings of JavadocTester at this time. JBS: https://bugs.openjdk.java.net/browse/JDK-8215516 Webrev: http://cr.openjdk.java.net/~jjg/8215516/webrev.00/ -- Jon From hannes.wallnoefer at oracle.com Wed Dec 19 13:43:32 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Wed, 19 Dec 2018 14:43:32 +0100 Subject: RFR: 8215291: Broken links when generating from project without modules Message-ID: Please review: Bug: https://bugs.openjdk.java.net/browse/JDK-8215291 Webrev: http://cr.openjdk.java.net/~hannesw/8215291/webrev.00/ No test for this functionality, but I?ve tested it manually with multiple sources. Hannes From priya.lakshmi.muthuswamy at oracle.com Thu Dec 20 04:38:52 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Thu, 20 Dec 2018 10:08:52 +0530 Subject: RFR: 8214738 : javadoc should honor styles in doc-files Message-ID: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> Hi, Kindly review the fix for https://bugs.openjdk.java.net/browse/JDK-8214738 webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ Thanks, Priya From jonathan.gibbons at oracle.com Thu Dec 20 18:39:06 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 20 Dec 2018 10:39:06 -0800 Subject: RFR: 8215291: Broken links when generating from project without modules In-Reply-To: References: Message-ID: <0d0f4d83-5f7f-670f-9acc-9d79a4cf507f@oracle.com> Looks OK to me. -- Jon On 12/19/2018 05:43 AM, Hannes Walln?fer wrote: > Please review: > > Bug: https://bugs.openjdk.java.net/browse/JDK-8215291 > Webrev: http://cr.openjdk.java.net/~hannesw/8215291/webrev.00/ > > No test for this functionality, but I?ve tested it manually with multiple sources. > > Hannes From jonathan.gibbons at oracle.com Thu Dec 20 19:31:18 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 20 Dec 2018 11:31:18 -0800 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> Message-ID: <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: > Hi, > > Kindly review the fix for > https://bugs.openjdk.java.net/browse/JDK-8214738 > webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ > > Thanks, > Priya > > I don't think you need to add anything (userHeaderTags etc) to Head. Head already has the requisite feature, "extraContent" and "addContent" which can be used to add content into the element. Re: Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) Don't use long-winded String comparison when you have type-safe comparison. In this case, you should be able to do something like ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD getLocalHeaderTags needlessly walks through all the element. You can break out of the loop once you hit . DocFilesHandlerImpl:196. The "if" statement is a waste of time and effort. The code will work perfectly well when localTagsContent is an empty list, so you can simplify 196-199 to just 197. TestCopyFiles.java (style) re: indenting the continuation of multi-line strings The general Java style for breaking long expressions is to break before a binary operator, not after. The style in other javadoc tests is to not indent the continuation expressions, so that it is easier to see how the first line and subsequent lines are aligned. -- Jon -------------- next part -------------- An HTML attachment was scrubbed... URL: From jonathan.gibbons at oracle.com Thu Dec 20 21:46:18 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 20 Dec 2018 13:46:18 -0800 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> Message-ID: Priya, In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. Since elements never have content, and so never have end elements, it seems misleading/incorrect to set the flag to true.? Also, you omit to handle ENTITY in the element, so I added that in as well.? You could also write this code as a visitor if you wanted, but the switch form is not too bad. I suggest the code should look something like this: 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean inHead = false; 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { 209 switch (dt.getKind()) { 210 case START_ELEMENT: 211 StartElementTree startElem = (StartElementTree) dt; switch (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case META: break; case TITLE: inTitle=true; break; default: if (inHead) { localTags.add(startElem); } } 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = (EndElementTree) dt; switch (HtmlTag.get(endElem)) { case HEAD: break loop; case TITLE: inTitle = false; break loop;default: if (inHead) { localTags.add(startElem); } } 235 break; case ENTITY: 236 case TEXT: 237 if (inHead && !inTitle) { 238 localTags.add(dt); 239 } 240 break; 241 } -- Jon On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: > > > > On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >> Hi, >> >> Kindly review the fix for >> https://bugs.openjdk.java.net/browse/JDK-8214738 >> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >> >> Thanks, >> Priya >> >> > > I don't think you need to add anything (userHeaderTags etc) to Head. > Head already has the requisite feature, "extraContent" and "addContent" > which can be used to add content into the <head> element. > > Re: > Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) > Don't use long-winded String comparison when you have type-safe > comparison. > In this case, you should be able to do something like > ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD > > getLocalHeaderTags needlessly walks through all the <body> element. > You can > break out of the loop once you hit </head>. > > DocFilesHandlerImpl:196. > The "if" statement is a waste of time and effort. The code will work > perfectly > well when localTagsContent is an empty list, so you can simplify > 196-199 to just 197. > > TestCopyFiles.java > (style) re: indenting the continuation of multi-line strings > The general Java style for breaking long expressions is to break > before a binary operator, not after. > The style in other javadoc tests is to not indent the continuation > expressions, so that it is easier > to see how the first line and subsequent lines are aligned. > > -- Jon -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181220/f1c5e784/attachment.html> From priya.lakshmi.muthuswamy at oracle.com Fri Dec 21 10:13:50 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Fri, 21 Dec 2018 15:43:50 +0530 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <d4401085-51cb-1c43-8f5d-43e3ca7ce5bf@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> <d4401085-51cb-1c43-8f5d-43e3ca7ce5bf@oracle.com> Message-ID: <b487b1ee-1eb5-3d80-ef53-8c516aa6ceb9@oracle.com> Hi Jon, Thanks for the review. I have made the following changes: 1)Added style tag in HtmlTag.java, before we were using style attribute for comparison. 2)utils.getPreamble(element) ignores new lines after html tags, so I can included them while fetching the localHeadTags. 3)In Head.java, used addContent() itself instead of new methods. I had seen the addContent(), but it was adding the content before the scripts/styles tags. The doc-files script/style needed to added at the end of the other styles it that it overrides them. When I checked the usage of addContent, i see that its been used only by IndexRedirectWriter to include script/noscript tags. I think that can be added at the end of existing tags as well. updated webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.01/ api: http://cr.openjdk.java.net/~pmuthuswamy/8214738/api/ some of the doc-file with user specific styles. api/jdk.jdi/com/sun/jdi/doc-files/signature.html api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html api/java.desktop/java/awt/doc-files/Modality.html Thanks, Priya On 12/21/2018 3:16 AM, Jonathan Gibbons wrote: > > Priya, > > In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. Since > <meta> elements never have content, and so never have end elements, it > seems misleading/incorrect to set the flag to true.? Also, you omit to > handle ENTITY in the <title> element, so I added that in as well.? You > could also write this code as a visitor if you wanted, but the switch > form is not too bad. > > I suggest the code should look something like this: > > 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean inHead = > false; > 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { > 209 switch (dt.getKind()) { > 210 case START_ELEMENT: > 211 StartElementTree startElem = (StartElementTree) dt; switch > (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case META: > break; case TITLE: inTitle=true; break; default: if (inHead) { > localTags.add(startElem); } } > 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = (EndElementTree) > dt; switch (HtmlTag.get(endElem)) { case HEAD: break loop; case TITLE: > inTitle = false; > break loop;default: if (inHead) { localTags.add(startElem); } } > 235 break; case ENTITY: 236 case TEXT: > 237 if (inHead && !inTitle) { > 238 localTags.add(dt); > 239 } > 240 break; > 241 } > -- Jon > > On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: >> >> >> >> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >>> Hi, >>> >>> Kindly review the fix for >>> https://bugs.openjdk.java.net/browse/JDK-8214738 >>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >>> >>> Thanks, >>> Priya >>> >>> >> >> I don't think you need to add anything (userHeaderTags etc) to Head. >> Head already has the requisite feature, "extraContent" and "addContent" >> which can be used to add content into the <head> element. >> >> Re: >> Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) >> Don't use long-winded String comparison when you have type-safe >> comparison. >> In this case, you should be able to do something like >> ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD >> >> getLocalHeaderTags needlessly walks through all the <body> element. >> You can >> break out of the loop once you hit </head>. >> >> DocFilesHandlerImpl:196. >> The "if" statement is a waste of time and effort. The code will work >> perfectly >> well when localTagsContent is an empty list, so you can simplify >> 196-199 to just 197. >> >> TestCopyFiles.java >> (style) re: indenting the continuation of multi-line strings >> The general Java style for breaking long expressions is to break >> before a binary operator, not after. >> The style in other javadoc tests is to not indent the continuation >> expressions, so that it is easier >> to see how the first line and subsequent lines are aligned. >> >> -- Jon > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181221/c2037384/attachment-0001.html> From hannes.wallnoefer at oracle.com Fri Dec 21 15:19:01 2018 From: hannes.wallnoefer at oracle.com (=?utf-8?Q?Hannes_Walln=C3=B6fer?=) Date: Fri, 21 Dec 2018 16:19:01 +0100 Subject: RFR: JDK-8215516: Move JavadocTester to a named package In-Reply-To: <84f3f7ce-79d3-52e9-489a-97e9dc606b9c@oracle.com> References: <84f3f7ce-79d3-52e9-489a-97e9dc606b9c@oracle.com> Message-ID: <30ADBCEA-B625-4672-86CC-447653AC595D@oracle.com> Hi Jon, Looks good to me, and tests run fine. Hannes > Am 18.12.2018 um 00:10 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: > > Please review a test-only change to move JavadocTester from the unnamed package to a new, named package. > > The name of the new package is "javadoc.tester.*". A number of alternatives were considered (javadoc.*, test.javadoc.*, javadoc.test.lib.*, etc) javadoc.tester.* seemed the least bad. In addition, the location of the library was moved up a level, to allow for more javadoc-related test library classes to be added going forward. > > Although conceptually simple, this does affect all tests that refer to it. There are up to 4 implications for each test. > > 1. Update the @library tag for the new location > 2. Update the @build tag > 3. Add an import for JavadocTester (and cleanup some other library imports, for toolbox classes) > 4. For some tests, update the @Test methods to be public > > Most (but not all) of the preceding changes were done by script and/or IDE. Some outlier cases were done manually, when checking that all tests still passed. > > One test, TestOrdering.java, required bigger changes, to change static nested classes to inner classes, to utilize access to protected methods. > > In TestRedirectLinks.java, there is a single-line, unrelated change to disconnect an HttpURLConnection, to help prevent test timeouts. > > Finally, in JavadocTester itself, the declaration for the @Test type was made public. > > There is no change to the functionality of any of the affected tests. After from the move, there are no other refactorings of JavadocTester at this time. > > JBS: https://bugs.openjdk.java.net/browse/JDK-8215516 > Webrev: http://cr.openjdk.java.net/~jjg/8215516/webrev.00/ > > -- Jon > From jonathan.gibbons at oracle.com Fri Dec 21 15:48:39 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 21 Dec 2018 07:48:39 -0800 Subject: RFR: JDK-8215516: Move JavadocTester to a named package In-Reply-To: <30ADBCEA-B625-4672-86CC-447653AC595D@oracle.com> References: <84f3f7ce-79d3-52e9-489a-97e9dc606b9c@oracle.com> <30ADBCEA-B625-4672-86CC-447653AC595D@oracle.com> Message-ID: <583e4b9b-5371-bd46-d4ef-c4112c4c3488@oracle.com> Thanks. This will unblock follow-up refactorings within JavadocTester itself. -- Jon On 12/21/18 7:19 AM, Hannes Walln?fer wrote: > Hi Jon, > > Looks good to me, and tests run fine. > > Hannes > > >> Am 18.12.2018 um 00:10 schrieb Jonathan Gibbons <jonathan.gibbons at oracle.com>: >> >> Please review a test-only change to move JavadocTester from the unnamed package to a new, named package. >> >> The name of the new package is "javadoc.tester.*". A number of alternatives were considered (javadoc.*, test.javadoc.*, javadoc.test.lib.*, etc) javadoc.tester.* seemed the least bad. In addition, the location of the library was moved up a level, to allow for more javadoc-related test library classes to be added going forward. >> >> Although conceptually simple, this does affect all tests that refer to it. There are up to 4 implications for each test. >> >> 1. Update the @library tag for the new location >> 2. Update the @build tag >> 3. Add an import for JavadocTester (and cleanup some other library imports, for toolbox classes) >> 4. For some tests, update the @Test methods to be public >> >> Most (but not all) of the preceding changes were done by script and/or IDE. Some outlier cases were done manually, when checking that all tests still passed. >> >> One test, TestOrdering.java, required bigger changes, to change static nested classes to inner classes, to utilize access to protected methods. >> >> In TestRedirectLinks.java, there is a single-line, unrelated change to disconnect an HttpURLConnection, to help prevent test timeouts. >> >> Finally, in JavadocTester itself, the declaration for the @Test type was made public. >> >> There is no change to the functionality of any of the affected tests. After from the move, there are no other refactorings of JavadocTester at this time. >> >> JBS: https://bugs.openjdk.java.net/browse/JDK-8215516 >> Webrev: http://cr.openjdk.java.net/~jjg/8215516/webrev.00/ >> >> -- Jon >> From jonathan.gibbons at oracle.com Fri Dec 21 15:54:41 2018 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Fri, 21 Dec 2018 07:54:41 -0800 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <b487b1ee-1eb5-3d80-ef53-8c516aa6ceb9@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> <d4401085-51cb-1c43-8f5d-43e3ca7ce5bf@oracle.com> <b487b1ee-1eb5-3d80-ef53-8c516aa6ceb9@oracle.com> Message-ID: <02869702-93b7-ac9a-8284-47090d825869@oracle.com> I've not yet read the full webrev, but I do have one immediate question, given below. -- Jon On 12/21/18 2:13 AM, Priya Lakshmi Muthuswamy wrote: > > Hi Jon, > > Thanks for the review. > > I have made the following changes: > 1)Added style tag in HtmlTag.java, before we were using style > attribute for comparison. > 2)utils.getPreamble(element) ignores new lines after html tags, so I > can included them while fetching the localHeadTags. > 3)In Head.java, used addContent() itself instead of new methods. > I had seen the addContent(), but it was adding the content before the > scripts/styles tags. > The doc-files script/style needed to added at the end of the other > styles it that it overrides them. > This is a red flag.? Why is it important that the user styles override the javadoc styles?? Given that we're adding javadoc styles for the javadoc header/navbar, isn't it important that those should appear as intended? > When I checked the usage of addContent, i see that its been used only > by IndexRedirectWriter to include script/noscript tags. > I think that can be added at the end of existing tags as well. > > updated webrev: http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.01/ > api: http://cr.openjdk.java.net/~pmuthuswamy/8214738/api/ > > some of the doc-file with user specific styles. > api/jdk.jdi/com/sun/jdi/doc-files/signature.html > api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html > api/java.desktop/java/awt/doc-files/Modality.html > > Thanks, > Priya > > On 12/21/2018 3:16 AM, Jonathan Gibbons wrote: >> >> Priya, >> >> In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. >> Since <meta> elements never have content, and so never have end >> elements, it seems misleading/incorrect to set the flag to true.? >> Also, you omit to handle ENTITY in the <title> element, so I added >> that in as well.? You could also write this code as a visitor if you >> wanted, but the switch form is not too bad. >> >> I suggest the code should look something like this: >> >> 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean inHead >> = false; >> 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { >> 209 switch (dt.getKind()) { >> 210 case START_ELEMENT: >> 211 StartElementTree startElem = (StartElementTree) dt; switch >> (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case META: >> break; case TITLE: inTitle=true; break; default: if (inHead) { >> localTags.add(startElem); } } >> 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = (EndElementTree) >> dt; switch (HtmlTag.get(endElem)) { case HEAD: break loop; case TITLE: >> inTitle = false; >> break loop;default: if (inHead) { localTags.add(startElem); } } >> 235 break; case ENTITY: 236 case TEXT: >> 237 if (inHead && !inTitle) { >> 238 localTags.add(dt); >> 239 } >> 240 break; >> 241 } >> -- Jon >> >> On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: >>> >>> >>> >>> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >>>> Hi, >>>> >>>> Kindly review the fix for >>>> https://bugs.openjdk.java.net/browse/JDK-8214738 >>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >>>> >>>> Thanks, >>>> Priya >>>> >>>> >>> >>> I don't think you need to add anything (userHeaderTags etc) to Head. >>> Head already has the requisite feature, "extraContent" and "addContent" >>> which can be used to add content into the <head> element. >>> >>> Re: >>> Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) >>> Don't use long-winded String comparison when you have type-safe >>> comparison. >>> In this case, you should be able to do something like >>> ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD >>> >>> getLocalHeaderTags needlessly walks through all the <body> element. >>> You can >>> break out of the loop once you hit </head>. >>> >>> DocFilesHandlerImpl:196. >>> The "if" statement is a waste of time and effort. The code will work >>> perfectly >>> well when localTagsContent is an empty list, so you can simplify >>> 196-199 to just 197. >>> >>> TestCopyFiles.java >>> (style) re: indenting the continuation of multi-line strings >>> The general Java style for breaking long expressions is to break >>> before a binary operator, not after. >>> The style in other javadoc tests is to not indent the continuation >>> expressions, so that it is easier >>> to see how the first line and subsequent lines are aligned. >>> >>> -- Jon >> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181221/424f7db3/attachment-0001.html> From priya.lakshmi.muthuswamy at oracle.com Wed Dec 26 04:05:21 2018 From: priya.lakshmi.muthuswamy at oracle.com (Priya Lakshmi Muthuswamy) Date: Wed, 26 Dec 2018 09:35:21 +0530 Subject: RFR: 8214738 : javadoc should honor styles in doc-files In-Reply-To: <02869702-93b7-ac9a-8284-47090d825869@oracle.com> References: <25ce1c9f-44d5-610d-507d-1ad5581db8b9@oracle.com> <8a04c5fe-1655-098f-4b92-d8dafb6b7714@oracle.com> <d4401085-51cb-1c43-8f5d-43e3ca7ce5bf@oracle.com> <b487b1ee-1eb5-3d80-ef53-8c516aa6ceb9@oracle.com> <02869702-93b7-ac9a-8284-47090d825869@oracle.com> Message-ID: <98d3a6e1-2c30-cd68-f036-aead52d65811@oracle.com> Hi Jon, Javadoc styles for header/navbar will appear as it is and will not get disturbed. I meant for any html content in doc-files, if there is any user-defined style, then those should override the javadoc styles. In html head element, default(javadoc) styles will be placed first and then those defined in doc-file. Thanks, Priya On 12/21/2018 9:24 PM, Jonathan Gibbons wrote: > I've not yet read the full webrev, but I do have one immediate > question, given below. > > -- Jon > > On 12/21/18 2:13 AM, Priya Lakshmi Muthuswamy wrote: >> >> Hi Jon, >> >> Thanks for the review. >> >> I have made the following changes: >> 1)Added style tag in HtmlTag.java, before we were using style >> attribute for comparison. >> 2)utils.getPreamble(element) ignores new lines after html tags, so I >> can included them while fetching the localHeadTags. >> 3)In Head.java, used addContent() itself instead of new methods. >> I had seen the addContent(), but it was adding the content before the >> scripts/styles tags. >> The doc-files script/style needed to added at the end of the other >> styles it that it overrides them. >> > This is a red flag.? Why is it important that the user styles override > the javadoc styles?? Given that we're adding javadoc styles for the > javadoc header/navbar, isn't it important that those should appear as > intended? > > >> When I checked the usage of addContent, i see that its been used only >> by IndexRedirectWriter to include script/noscript tags. >> I think that can be added at the end of existing tags as well. >> >> updated webrev: >> http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.01/ >> api: http://cr.openjdk.java.net/~pmuthuswamy/8214738/api/ >> >> some of the doc-file with user specific styles. >> api/jdk.jdi/com/sun/jdi/doc-files/signature.html >> api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html >> api/java.desktop/java/awt/doc-files/Modality.html >> >> Thanks, >> Priya >> >> On 12/21/2018 3:16 AM, Jonathan Gibbons wrote: >>> >>> Priya, >>> >>> In DocFilesHandlerImpl, you have a boolean flag titleOrMetaTags. >>> Since <meta> elements never have content, and so never have end >>> elements, it seems misleading/incorrect to set the flag to true.? >>> Also, you omit to handle ENTITY in the <title> element, so I added >>> that in as well.? You could also write this code as a visitor if you >>> wanted, but the switch form is not too bad. >>> >>> I suggest the code should look something like this: >>> >>> 205 List<DocTree> localTags = new ArrayList<>(); ?206 boolean inHead >>> = false; >>> 207 boolean inTitle = false; loop: 208 for (DocTree dt : dtrees) { >>> 209 switch (dt.getKind()) { >>> 210 case START_ELEMENT: >>> 211 StartElementTree startElem = (StartElementTree) dt; switch >>> (HtmlTag.get(startElem)) { case HEAD: inHead = true; break;case >>> META: break; case TITLE: inTitle=true; break; default: if (inHead) { >>> localTags.add(startElem); } } >>> 223 break; 224 case END_ELEMENT: ?211 EndElementTree endElem = (EndElementTree) >>> dt; switch (HtmlTag.get(endElem)) { case HEAD: break loop; case TITLE: >>> inTitle = false; >>> break loop;default: if (inHead) { localTags.add(startElem); } } >>> 235 break; case ENTITY: 236 case TEXT: >>> 237 if (inHead && !inTitle) { >>> 238 localTags.add(dt); >>> 239 } >>> 240 break; >>> 241 } >>> -- Jon >>> >>> On 12/20/2018 11:31 AM, Jonathan Gibbons wrote: >>>> >>>> >>>> >>>> On 12/19/2018 08:38 PM, Priya Lakshmi Muthuswamy wrote: >>>>> Hi, >>>>> >>>>> Kindly review the fix for >>>>> https://bugs.openjdk.java.net/browse/JDK-8214738 >>>>> webrev : http://cr.openjdk.java.net/~pmuthuswamy/8214738/webrev.00/ >>>>> >>>>> Thanks, >>>>> Priya >>>>> >>>>> >>>> >>>> I don't think you need to add anything (userHeaderTags etc) to Head. >>>> Head already has the requisite feature, "extraContent" and "addContent" >>>> which can be used to add content into the <head> element. >>>> >>>> Re: >>>> Utils.toLowerCase(nodeEnd.getName().toString()).equals(HtmlTag.HEAD.getText()) >>>> Don't use long-winded String comparison when you have type-safe >>>> comparison. >>>> In this case, you should be able to do something like >>>> ??? HtmlTag.get(nodeEnd.getName()) == HtmlTag.HEAD >>>> >>>> getLocalHeaderTags needlessly walks through all the <body> element. >>>> You can >>>> break out of the loop once you hit </head>. >>>> >>>> DocFilesHandlerImpl:196. >>>> The "if" statement is a waste of time and effort. The code will >>>> work perfectly >>>> well when localTagsContent is an empty list, so you can simplify >>>> 196-199 to just 197. >>>> >>>> TestCopyFiles.java >>>> (style) re: indenting the continuation of multi-line strings >>>> The general Java style for breaking long expressions is to break >>>> before a binary operator, not after. >>>> The style in other javadoc tests is to not indent the continuation >>>> expressions, so that it is easier >>>> to see how the first line and subsequent lines are aligned. >>>> >>>> -- Jon >>> -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181226/b947da6a/attachment.html> From tschoening at am-soft.de Fri Dec 28 12:48:15 2018 From: tschoening at am-soft.de (=?utf-8?Q?Thorsten_Sch=C3=B6ning?=) Date: Fri, 28 Dec 2018 13:48:15 +0100 Subject: Unclear docs regarding escaping of Windows paths. Message-ID: <967711604.20181228134815@am-soft.de> Hi all, this question is related to an issue raised for the javadoc plugin of Maven[1], which doesn't seem to escape paths forwarded to argument files supported by javadoc on Windows. The problem is that the docs have changed regarding such details in the last versions of the JDK and it's unclear currently how to escape paths properly when and what to not escape etc. The following is for Java 7: > If a filename contains embedded spaces, put the whole filename in > double quotes, and double each backslash ("My Files\Stuff.java"). https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles The following from Java 8: > If a file name contains embedded spaces, then put the whole file > name in double quotation marks. https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html In docs of Java 11 that part is completely missing, no mention of quotes, spaces or backslashes anymore: https://docs.oracle.com/en/java/javase/11/javadoc/javadoc-command.html#GUID-EFE927BC-DB00-4876-808C-ED23E1AAEF7D If you have a look at the URIs, in former versions of the JDK they were Windows-specific, while the last one is not. So I guess things have been refactored and some details of the argument files have been simply lost by accident. Or it might be by purpose for some reason. The interesting thing is that e.g. the following example for parts of an argument file are still there: > -overview \java\jdk9\docs\api\overview-summary.html But regarding the docs of Java 7 that example is wrong, because it uses single backslashes only and as MJAVADOC-469 proves, those don't work properly in paths of argument files. So, could someone please have a look at the docs and why such important details like those for when to escape backslashes have been removed? And readd some or some more clarification, at least at the level of JDK 7? Even in JDK 7 there's no definitive answer to the question if backslash is a general escape character, only examples of using them as such. One is paths under Windows, the other colons in tag names, which are not mentioned anymore in JDK 11 as well. It would be great if this whole thing could be cleared up so that people generating the argument files know for sure when to escape backslashes and when not. MJAVADOC-469 proposes a regular expression currently which escapes backslashes if not already escaped or being part of a tag name. That doesn't handle a mixture of escaped and unescaped backslashes and applies the replacement to everything in lack of knowing what a path is currently. But it fixes the one problem with unescaped paths and shouldn't break too much else in case of wrong escaping. OTOH, it might be that all backslashes need to be escaped anyway, one simply doesn't know currently. > (?<!\\)\\(?!\\|:) > additionalOption = additionalOption.replaceAll("(?<!\\\\)\\\\(?!\\\\|:)", "\\\\"); https://issues.apache.org/jira/browse/MJAVADOC-469?focusedCommentId=16729567&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-16729567 Before raising this a s bug somewhere, I was trying to get some more insights here, maybe someone already able and willing to clarify the docs or able to tell me where to raise a bug etc. I'm feeling a bit lost currently. Thanks! [1]: https://issues.apache.org/jira/browse/MJAVADOC-469 Mit freundlichen Gr??en, Thorsten Sch?ning -- Thorsten Sch?ning E-Mail: Thorsten.Schoening at AM-SoFT.de AM-SoFT IT-Systeme http://www.AM-SoFT.de/ Telefon...........05151- 9468- 55 Fax...............05151- 9468- 88 Mobil..............0178-8 9468- 04 AM-SoFT GmbH IT-Systeme, Brandenburger Str. 7c, 31789 Hameln AG Hannover HRB 207 694 - Gesch?ftsf?hrer: Andreas Muchow