` elements with top level CSS classes that identify the kind of signature: `module-signature`, `package-signature`, `type-signature` and `member-signature`. Signature components are rendered as `` elements with CSS classes that identify the component, e.g.: `modifiers`, `annotations`, `element-name`, `exceptions`. > > As a side benefit, this PR reduces the number of methods in `HtmlDocletWriter` used to generate annotation information. Generally, very nice to see this continuation of the improvements to handle signatures. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java line 300: > 298: Set subclasses = classtree.directSubClasses(typeElement, false); > 299: if (!subclasses.isEmpty()) { > 300: HtmlTree dl = HtmlTree.DL(HtmlStyle.notes); I'm surprised this has gone; is this intentional? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1681: > 1679: > 1680: /** > 1681: * Return a content tree containing the annotation types for the given Element. (minor) either put type names (Element) in code font or use English equivalent (element). src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1686: > 1684: * @param lineBreak if true add new line between each member value > 1685: * @return the documentation tree to which the annotation info will be > 1686: * added The method is `getAnnotationInfo` so it seems strange/confusing to return an object to which the info _will be_ added (future tense.) I'm surprised it's not a documentation tree containing the annotation info. Is this a hangover from the old code? src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1693: > 1691: > 1692: /** > 1693: * Return a content tree containing the annotation types for the given element. `Returns` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1718: > 1716: * > 1717: * @param descList a list of annotation mirrors. > 1718: * @param lineBreak if true, add new line between each member value. Funny typo ;-) Good catch! src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 531: > 529: // > 530: // > 531: // The following constants are used for the components of a signature of an element Two lines earlier, line 529, change `member signature` to `signatures` src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 490: > 488: .deprecated-content { > 489: margin:0; > 490: padding:10px 0; Yay! Good improvement. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/966 From jjg at openjdk.java.net Thu Nov 26 19:30:59 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 26 Nov 2020 19:30:59 GMT Subject: RFR: JDK-8248566: Make API docs more usable on mobile browsers In-Reply-To: References: Message-ID: On Mon, 2 Nov 2020 14:41:15 GMT, Hannes Walln?fer wrote: > The purpose of this change is to make javadoc generated pages more usable on devices with smaller screens such as phones and tablets. Changes are mostly in `stylesheet.css` along with a few small changes in generated HTML pages. > > - A `viewport` meta tag is added to every page to tell browsers that the page is optimized for small screens and shouldn't be rendered using desktop dimensions and scaled down to actual browser size. > - The right-floating `about-language` element is moved forward before the list of main navigation links, and the display style of that list is changed to `block`. This allows the navigation links to wrap around the `about-language` div when space gets tight. Also, navigation `height` entries are changed to `min-height` so they can grow when broken to more than one line. > - Media queries are added to slightly shrink various page components for smaller browser widths. This includes the search input, navigation bar fonts and various spacings within the page. > > API docs rendered with this change can be viewed here (overview and java.base module pages only): > > http://cr.openjdk.java.net/~hannesw/8248566/api.02/ > > The page should look the same as before the change when viewed in a normal-sized desktop browser. The changes should be visible when resizing the browser window, viewing the page with a mobile browser emulator (available in developer tools of various desktop browsers) or viewing the page on a mobile device. Nice! I like the interaction with the recent changes to table and grid layout. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/1008 From jjg at openjdk.java.net Thu Nov 26 19:36:58 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 26 Nov 2020 19:36:58 GMT Subject: RFR: JDK-8248566: Make API docs more usable on mobile browsers In-Reply-To: References:

Message-ID: On Thu, 26 Nov 2020 19:27:49 GMT, Jonathan Gibbons wrote: >> The purpose of this change is to make javadoc generated pages more usable on devices with smaller screens such as phones and tablets. Changes are mostly in `stylesheet.css` along with a few small changes in generated HTML pages. >> >> - A `viewport` meta tag is added to every page to tell browsers that the page is optimized for small screens and shouldn't be rendered using desktop dimensions and scaled down to actual browser size. >> - The right-floating `about-language` element is moved forward before the list of main navigation links, and the display style of that list is changed to `block`. This allows the navigation links to wrap around the `about-language` div when space gets tight. Also, navigation `height` entries are changed to `min-height` so they can grow when broken to more than one line. >> - Media queries are added to slightly shrink various page components for smaller browser widths. This includes the search input, navigation bar fonts and various spacings within the page. >> >> API docs rendered with this change can be viewed here (overview and java.base module pages only): >> >> http://cr.openjdk.java.net/~hannesw/8248566/api.02/ >> >> The page should look the same as before the change when viewed in a normal-sized desktop browser. The changes should be visible when resizing the browser window, viewing the page with a mobile browser emulator (available in developer tools of various desktop browsers) or viewing the page on a mobile device. > > Nice! I like the interaction with the recent changes to table and grid layout. Impressive on a small older mobile phone! ------------- PR: https://git.openjdk.java.net/jdk/pull/1008 From jjg at openjdk.java.net Thu Nov 26 19:39:56 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 26 Nov 2020 19:39:56 GMT Subject: RFR: JDK-8254893: Fix display of search tag results without holder information In-Reply-To: References: Message-ID: On Thu, 5 Nov 2020 15:42:07 GMT, Hannes Walln?fer wrote: > This is a trivial fix to only display holder information for index items in search results if it is available. Ah, it's one of those "hard" reviews" ... Sorry for the delay. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/1077 From jjg at openjdk.java.net Thu Nov 26 20:07:02 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 26 Nov 2020 20:07:02 GMT Subject: RFR: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: References: Message-ID: <73qAS1XmpPR6GbO7Pr-4TbVLNDg0BXBUE3yKfgXjyT4=.c5dabe8c-9c13-4420-9ef1-065d2e9f0aaf@github.com> On Fri, 20 Nov 2020 15:00:56 GMT, Hannes Walln?fer wrote: > This PR softens the case-sensitivity rules in Javadoc searches by including results of case-insensitive search if a case-sensitive yields no or very few results. > > Changes also include some restructuring of the search.js code along with minor changes that improve compliance with the specification (Segments separated by `_` are ranked the same way as segments of CamelCase identifiers, and matches on such segments are ranked lower than matches for whole identifiers, which wasn't always the case previously) > > The `TestSearchScript.java` test, which has been disabled with the removal of Nashorn, has been updated to run without failure. In the process, I noticed that the recent IndexBuilder|Writer|Item refactoring, comparators have been unified to the point that the same item order is used in HTML index pages and the search index JSON files. However, there used to be slight differences in the sorting between the two. This change restores the original order by adding two simple search index comparators to `IndexBuilder.java`. > > API documentation generated with this PR applied can be viewed and tested here: > http://cr.openjdk.java.net/~hannesw/8244535/api.01/ There is a certain amount of "two steps forward, one step back" here. Yes, this is a good fix to the regression, so approved, and maybe it was an embarrassing convenience that the search test was disabled for the IndexBuilder work, but it is retrograde in that we're going back to a world with different sort orders for the static index pages, and interactive search. FWIW, I like the conciseness of the change, which also helps highlight when comparators would be different ... i.e. for type elements with the same simple name. With that in mind, I came up with the "test case" for when the comparators are different: the `ToolProvider` class, which is in both `java.util.spi` and `java.tools`, and these two instances sort differently in the two presentations. Bottom line: this is a good fix, and a step in the right direction, but we should follow up with another fix to have the static index pages sort the same as the index pages. I'm guessing that may mean reverting part of this change and improving `mainComparator`. ------------- Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/1354 From jonathan.gibbons at oracle.com Thu Nov 26 20:09:18 2020 From: jonathan.gibbons at oracle.com (Jonathan Gibbons) Date: Thu, 26 Nov 2020 12:09:18 -0800 Subject: RFR: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: <9F2niPqdydCp54-rPqvnzqhke8HhYM78CLh6eVI3Se4=.f18d0963-f8f1-4fd7-9baa-0e13e9abe2c4@github.com> References: <9F2niPqdydCp54-rPqvnzqhke8HhYM78CLh6eVI3Se4=.f18d0963-f8f1-4fd7-9baa-0e13e9abe2c4@github.com> Message-ID: <32aed661-e459-420c-c57e-98a98f302432@oracle.com> Pavel, The way I read the code changes, you need to find examples of classes with the same name but in different packages.? The example that came to mind for me is `ToolProvider`. -- Jon On 11/26/20 8:51 AM, Pavel Rappo wrote: > On Fri, 20 Nov 2020 15:00:56 GMT, Hannes Walln?fer wrote: > >> This PR softens the case-sensitivity rules in Javadoc searches by including results of case-insensitive search if a case-sensitive yields no or very few results. >> >> Changes also include some restructuring of the search.js code along with minor changes that improve compliance with the specification (Segments separated by `_` are ranked the same way as segments of CamelCase identifiers, and matches on such segments are ranked lower than matches for whole identifiers, which wasn't always the case previously) >> >> The `TestSearchScript.java` test, which has been disabled with the removal of Nashorn, has been updated to run without failure. In the process, I noticed that the recent IndexBuilder|Writer|Item refactoring, comparators have been unified to the point that the same item order is used in HTML index pages and the search index JSON files. However, there used to be slight differences in the sorting between the two. This change restores the original order by adding two simple search index comparators to `IndexBuilder.java`. >> >> API documentation generated with this PR applied can be viewed and tested here: >> http://cr.openjdk.java.net/~hannesw/8244535/api.01/ > @hns, could you recommend (at least several different) example searches that would clearly show the advantages of this proposal over [JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/index.html)? Although the are examples in tests, they are contrived (naturally). It would be nice to see how this improves search on a real codebase, such as the JDK codebase. > > ------------- > > PR: https://git.openjdk.java.net/jdk/pull/1354 From pavel.rappo at oracle.com Thu Nov 26 20:36:01 2020 From: pavel.rappo at oracle.com (Pavel Rappo) Date: Thu, 26 Nov 2020 20:36:01 +0000 Subject: RFR: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: <32aed661-e459-420c-c57e-98a98f302432@oracle.com> References: <9F2niPqdydCp54-rPqvnzqhke8HhYM78CLh6eVI3Se4=.f18d0963-f8f1-4fd7-9baa-0e13e9abe2c4@github.com> <32aed661-e459-420c-c57e-98a98f302432@oracle.com> Message-ID: When I punch in `ToolProvider` I see 3 results in JDK 15 and 2 results on this change's sample page. Advantages are unclear. [JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/index.html): Types java.util.spi.ToolProvider javax.tools.ToolProvider Members javax.tools.ToolProvider.ToolProvider() [This change's sample page](http://cr.openjdk.java.net/~hannesw/8244535/api.01/): Types java.util.spi.ToolProvider javax.tools.ToolProvider Do you see a different picture? > On 26 Nov 2020, at 20:09, Jonathan Gibbons wrote: > > Pavel, > > The way I read the code changes, you need to find examples of classes with the same name but in different packages. The example that came to mind for me is `ToolProvider`. > > -- Jon > > On 11/26/20 8:51 AM, Pavel Rappo wrote: >> On Fri, 20 Nov 2020 15:00:56 GMT, Hannes Walln?fer wrote: >> >>> This PR softens the case-sensitivity rules in Javadoc searches by including results of case-insensitive search if a case-sensitive yields no or very few results. >>> >>> Changes also include some restructuring of the search.js code along with minor changes that improve compliance with the specification (Segments separated by `_` are ranked the same way as segments of CamelCase identifiers, and matches on such segments are ranked lower than matches for whole identifiers, which wasn't always the case previously) >>> >>> The `TestSearchScript.java` test, which has been disabled with the removal of Nashorn, has been updated to run without failure. In the process, I noticed that the recent IndexBuilder|Writer|Item refactoring, comparators have been unified to the point that the same item order is used in HTML index pages and the search index JSON files. However, there used to be slight differences in the sorting between the two. This change restores the original order by adding two simple search index comparators to `IndexBuilder.java`. >>> >>> API documentation generated with this PR applied can be viewed and tested here: >>> http://cr.openjdk.java.net/~hannesw/8244535/api.01/ >> @hns, could you recommend (at least several different) example searches that would clearly show the advantages of this proposal over [JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/index.html)? Although the are examples in tests, they are contrived (naturally). It would be nice to see how this improves search on a real codebase, such as the JDK codebase. >> >> ------------- >> >> PR: https://git.openjdk.java.net/jdk/pull/1354 From jjg at openjdk.java.net Thu Nov 26 22:38:57 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 26 Nov 2020 22:38:57 GMT Subject: RFR: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: <73qAS1XmpPR6GbO7Pr-4TbVLNDg0BXBUE3yKfgXjyT4=.c5dabe8c-9c13-4420-9ef1-065d2e9f0aaf@github.com> References: <73qAS1XmpPR6GbO7Pr-4TbVLNDg0BXBUE3yKfgXjyT4=.c5dabe8c-9c13-4420-9ef1-065d2e9f0aaf@github.com> Message-ID: On Thu, 26 Nov 2020 20:04:17 GMT, Jonathan Gibbons wrote: >> This PR softens the case-sensitivity rules in Javadoc searches by including results of case-insensitive search if a case-sensitive yields no or very few results. >> >> Changes also include some restructuring of the search.js code along with minor changes that improve compliance with the specification (Segments separated by `_` are ranked the same way as segments of CamelCase identifiers, and matches on such segments are ranked lower than matches for whole identifiers, which wasn't always the case previously) >> >> The `TestSearchScript.java` test, which has been disabled with the removal of Nashorn, has been updated to run without failure. In the process, I noticed that the recent IndexBuilder|Writer|Item refactoring, comparators have been unified to the point that the same item order is used in HTML index pages and the search index JSON files. However, there used to be slight differences in the sorting between the two. This change restores the original order by adding two simple search index comparators to `IndexBuilder.java`. >> >> API documentation generated with this PR applied can be viewed and tested here: >> http://cr.openjdk.java.net/~hannesw/8244535/api.01/ > > There is a certain amount of "two steps forward, one step back" here. > > Yes, this is a good fix to the regression, so approved, and maybe it was an embarrassing convenience that the search test was disabled for the IndexBuilder work, but it is retrograde in that we're going back to a world with different sort orders for the static index pages, and interactive search. > > FWIW, I like the conciseness of the change, which also helps highlight when comparators would be different ... i.e. for type elements with the same simple name. With that in mind, I came up with the "test case" for when the comparators are different: the `ToolProvider` class, which is in both `java.util.spi` and `java.tools`, and these two instances sort differently in the two presentations. > > Bottom line: this is a good fix, and a step in the right direction, but we should follow up with another fix to have the static index pages sort the same as the index pages. I'm guessing that may mean reverting part of this change and improving `mainComparator`. I thought I saw a different order in the type declarations. I'll check again. -- Jon On 11/26/20 12:38 PM, mlbridge[bot] wrote: > > /Mailing list message from Pavel Rappo > on javadoc-dev :/ > > When I punch in `ToolProvider` I see 3 results in JDK 15 and 2 results > on this change's sample page. Advantages are unclear. > > [JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/index.html): > > Types > java.util.spi.ToolProvider > javax.tools.ToolProvider > Members > javax.tools.ToolProvider.ToolProvider() > > [This change's sample > page](http://cr.openjdk.java.net/~hannesw/8244535/api.01/): > > Types > java.util.spi.ToolProvider > javax.tools.ToolProvider > > Do you see a different picture? > > On 26 Nov 2020, at 20:09, Jonathan Gibbons oracle.com> wrote: > > Pavel, > > The way I read the code changes, you need to find examples of > classes with the same name but in different packages. The example > that came to mind for me is `ToolProvider`. > > -- Jon > > On 11/26/20 8:51 AM, Pavel Rappo wrote: > > ? > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > , > or unsubscribe > . > ------------- PR: https://git.openjdk.java.net/jdk/pull/1354 From jjg at openjdk.java.net Thu Nov 26 22:52:58 2020 From: jjg at openjdk.java.net (Jonathan Gibbons) Date: Thu, 26 Nov 2020 22:52:58 GMT Subject: RFR: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: References: <73qAS1XmpPR6GbO7Pr-4TbVLNDg0BXBUE3yKfgXjyT4=.c5dabe8c-9c13-4420-9ef1-065d2e9f0aaf@github.com> Message-ID: <8WRQItkf_lGiM4t8d4jeihUSwiNFnC3p2ZhnGnWC_aE=.08984d4c-773c-43fb-9e3a-28119d4b6c8f@github.com> On Thu, 26 Nov 2020 22:36:01 GMT, Jonathan Gibbons wrote: >> There is a certain amount of "two steps forward, one step back" here. >> >> Yes, this is a good fix to the regression, so approved, and maybe it was an embarrassing convenience that the search test was disabled for the IndexBuilder work, but it is retrograde in that we're going back to a world with different sort orders for the static index pages, and interactive search. >> >> FWIW, I like the conciseness of the change, which also helps highlight when comparators would be different ... i.e. for type elements with the same simple name. With that in mind, I came up with the "test case" for when the comparators are different: the `ToolProvider` class, which is in both `java.util.spi` and `java.tools`, and these two instances sort differently in the two presentations. >> >> Bottom line: this is a good fix, and a step in the right direction, but we should follow up with another fix to have the static index pages sort the same as the index pages. I'm guessing that may mean reverting part of this change and improving `mainComparator`. > > I thought I saw a different order in the type declarations. I'll check > again. > > -- Jon > > On 11/26/20 12:38 PM, mlbridge[bot] wrote: >> >> /Mailing list message from Pavel Rappo >> on javadoc-dev :/ >> >> When I punch in `ToolProvider` I see 3 results in JDK 15 and 2 results >> on this change's sample page. Advantages are unclear. >> >> [JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/index.html): >> >> Types >> java.util.spi.ToolProvider >> javax.tools.ToolProvider >> Members >> javax.tools.ToolProvider.ToolProvider() >> >> [This change's sample >> page](http://cr.openjdk.java.net/~hannesw/8244535/api.01/): >> >> Types >> java.util.spi.ToolProvider >> javax.tools.ToolProvider >> >> Do you see a different picture? >> >> On 26 Nov 2020, at 20:09, Jonathan Gibbons > oracle.com> wrote: >> >> Pavel, >> >> The way I read the code changes, you need to find examples of >> classes with the same name but in different packages. The example >> that came to mind for me is `ToolProvider`. >> >> -- Jon >> >> On 11/26/20 8:51 AM, Pavel Rappo wrote: >> >> ? >> You are receiving this because you were mentioned. >> Reply to this email directly, view it on GitHub >> , >> or unsubscribe >> . >> With the change, the behavior with the proposed patch is back to being the same as JDK 15, which is the indirect result of the direct goal to fix a broken test. However, with the change, the sort order of the two instances of ToolProvider is different in the interactive search and static index. This is a change from recent behavior in JDK 16 where the sort order is the same. Until this patch is pushed and a new promotion published, you can see the recent JDK 16 behavior here: https://download.java.net/java/early_access/jdk16/docs/api/index.html ------------- PR: https://git.openjdk.java.net/jdk/pull/1354 From hannesw at openjdk.java.net Fri Nov 27 09:46:58 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 09:46:58 GMT Subject: Integrated: 8242652: Throw SkippedException if no JS engine availabe in TestSearchScript In-Reply-To: References: Message-ID: On Tue, 24 Nov 2020 15:08:27 GMT, Hannes Walln?fer wrote: > This is a simple change to throw jtreg.SkippedException if no JavaScript engine is available to run the TestSearchScript test. In my previous attempt I tried to use the SkippedException class already present elsewhere in the test tree, not realizing I couuld just copy/create the exception in the javadoc test library. > > Note that while the test is skipped correctly if no JS engine is available, the test will currently fail in the presence of a JS engine such as GraalJS. This is fixed by JDK-8244535. This pull request has now been integrated. Changeset: f2f3ba92 Author: Hannes Walln?fer URL: https://git.openjdk.java.net/jdk/commit/f2f3ba92 Stats: 20 lines in 2 files changed: 8 ins; 10 del; 2 mod 8242652: Throw SkippedException if no JS engine availabe in TestSearchScript Reviewed-by: prappo ------------- PR: https://git.openjdk.java.net/jdk/pull/1412 From hannesw at openjdk.java.net Fri Nov 27 13:24:55 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 13:24:55 GMT Subject: Integrated: JDK-8254893: Fix display of search tag results without holder information In-Reply-To: References: Message-ID: On Thu, 5 Nov 2020 15:42:07 GMT, Hannes Walln?fer wrote: > This is a trivial fix to only display holder information for index items in search results if it is available. This pull request has now been integrated. Changeset: 78fdb65d Author: Hannes Walln?fer URL: https://git.openjdk.java.net/jdk/commit/78fdb65d Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod 8254893: Fix display of search tag results without holder information Reviewed-by: jjg ------------- PR: https://git.openjdk.java.net/jdk/pull/1077 From hannesw at openjdk.java.net Fri Nov 27 15:23:56 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 15:23:56 GMT Subject: RFR: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: References: Message-ID: On Fri, 20 Nov 2020 15:00:56 GMT, Hannes Walln?fer wrote: > This PR softens the case-sensitivity rules in Javadoc searches by including results of case-insensitive search if a case-sensitive yields no or very few results. > > Changes also include some restructuring of the search.js code along with minor changes that improve compliance with the specification (Segments separated by `_` are ranked the same way as segments of CamelCase identifiers, and matches on such segments are ranked lower than matches for whole identifiers, which wasn't always the case previously) > > The `TestSearchScript.java` test, which has been disabled with the removal of Nashorn, has been updated to run without failure. In the process, I noticed that the recent IndexBuilder|Writer|Item refactoring, comparators have been unified to the point that the same item order is used in HTML index pages and the search index JSON files. However, there used to be slight differences in the sorting between the two. This change restores the original order by adding two simple search index comparators to `IndexBuilder.java`. > > API documentation generated with this PR applied can be viewed and tested here: > http://cr.openjdk.java.net/~hannesw/8244535/api.01/ > @hns, could you recommend (at least several different) example searches that would clearly show the advantages of this proposal over [JDK 15](https://docs.oracle.com/en/java/javase/15/docs/api/index.html)? Although the are examples in tests, they are contrived (naturally). It would be nice to see how this improves search on a real codebase, such as the JDK codebase. For case insensitivity, you can search for "HTTPC" to find `HttpClient` (or any other name where you get capitalization wrong). For the tweaks and fixes in result ranking, you can search for "get". Previously you got several variables with longer names containing "GET" ranked at the top of the result, now it's GET and get() at the top. I have a few searches I routinely do to detect and understand changes in search behaviour, but honestly I think there is nothing special about these searches. :) ------------- PR: https://git.openjdk.java.net/jdk/pull/1354 From hannesw at openjdk.java.net Fri Nov 27 15:30:56 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 15:30:56 GMT Subject: Integrated: 8244535: JavaDoc search is overly strict with letter case In-Reply-To: References: Message-ID: On Fri, 20 Nov 2020 15:00:56 GMT, Hannes Walln?fer wrote: > This PR softens the case-sensitivity rules in Javadoc searches by including results of case-insensitive search if a case-sensitive yields no or very few results. > > Changes also include some restructuring of the search.js code along with minor changes that improve compliance with the specification (Segments separated by `_` are ranked the same way as segments of CamelCase identifiers, and matches on such segments are ranked lower than matches for whole identifiers, which wasn't always the case previously) > > The `TestSearchScript.java` test, which has been disabled with the removal of Nashorn, has been updated to run without failure. In the process, I noticed that the recent IndexBuilder|Writer|Item refactoring, comparators have been unified to the point that the same item order is used in HTML index pages and the search index JSON files. However, there used to be slight differences in the sorting between the two. This change restores the original order by adding two simple search index comparators to `IndexBuilder.java`. > > API documentation generated with this PR applied can be viewed and tested here: > http://cr.openjdk.java.net/~hannesw/8244535/api.01/ This pull request has now been integrated. Changeset: 53d14442 Author: Hannes Walln?fer URL: https://git.openjdk.java.net/jdk/commit/53d14442 Stats: 201 lines in 5 files changed: 66 ins; 52 del; 83 mod 8244535: JavaDoc search is overly strict with letter case Reviewed-by: jjg ------------- PR: https://git.openjdk.java.net/jdk/pull/1354 From hannesw at openjdk.java.net Fri Nov 27 15:34:59 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 15:34:59 GMT Subject: Integrated: JDK-8248566: Make API docs more usable on mobile browsers In-Reply-To: References: Message-ID: On Mon, 2 Nov 2020 14:41:15 GMT, Hannes Walln?fer wrote: > The purpose of this change is to make javadoc generated pages more usable on devices with smaller screens such as phones and tablets. Changes are mostly in `stylesheet.css` along with a few small changes in generated HTML pages. > > - A `viewport` meta tag is added to every page to tell browsers that the page is optimized for small screens and shouldn't be rendered using desktop dimensions and scaled down to actual browser size. > - The right-floating `about-language` element is moved forward before the list of main navigation links, and the display style of that list is changed to `block`. This allows the navigation links to wrap around the `about-language` div when space gets tight. Also, navigation `height` entries are changed to `min-height` so they can grow when broken to more than one line. > - Media queries are added to slightly shrink various page components for smaller browser widths. This includes the search input, navigation bar fonts and various spacings within the page. > > API docs rendered with this change can be viewed here (overview and java.base module pages only): > > http://cr.openjdk.java.net/~hannesw/8248566/api.02/ > > The page should look the same as before the change when viewed in a normal-sized desktop browser. The changes should be visible when resizing the browser window, viewing the page with a mobile browser emulator (available in developer tools of various desktop browsers) or viewing the page on a mobile device. This pull request has now been integrated. Changeset: 644271e7 Author: Hannes Walln?fer URL: https://git.openjdk.java.net/jdk/commit/644271e7 Stats: 81 lines in 4 files changed: 70 ins; 6 del; 5 mod 8248566: Make API docs more usable on mobile browsers Reviewed-by: jjg ------------- PR: https://git.openjdk.java.net/jdk/pull/1008 From rriggs at openjdk.java.net Fri Nov 27 16:35:55 2020 From: rriggs at openjdk.java.net (Roger Riggs) Date: Fri, 27 Nov 2020 16:35:55 GMT Subject: RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations. In-Reply-To: References: Message-ID: On Fri, 20 Nov 2020 17:15:22 GMT, Jonathan Gibbons wrote: > This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description. > > The goal is to be able to simplify the following common pattern: > > /** > * Returns the result. Optional additional text. > * @return the result > */ > int method() { > > by > > /** > * {@return the result} Optional additional text. > */ > int method() { > > Note: > > * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere. > * The expansion of the inline tag is `Returns " _content_ `.` where _content_ is the content of the tag. > * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description > * The inline tag can be inherited into overriding methods as if it was provided as a block tag. /** * {@return the result} Optional additional text. */ ``` The java source looks a bit odd/unusual because the "first sentence" does not appear to end with a period. Though it seems like a convenience to include the '.' in the expansion, the source might be clearer if it did not, as in: /** * {@return the result}. Optional additional text. */ Similarly, prepending the "Returns", forces the verb, which is conventional but always the most appropriate word. Changing the expansion to be only the contents of @ return would allow more flexible use. It would put more responsibility on the developer to form the first sentence. (With "Returns"... and the "." outside the tag. ------------- PR: https://git.openjdk.java.net/jdk/pull/1355 From hannesw at openjdk.java.net Fri Nov 27 17:14:59 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 17:14:59 GMT Subject: RFR: JDK-8245058: improve presentation of annotations for modules and packages In-Reply-To: References:

Message-ID: On Thu, 26 Nov 2020 17:59:33 GMT, Jonathan Gibbons wrote: >> This PR adds a dedicated signature to module and package overview pages and moves all code for generating signatures to a new `doclets.formats.html.Signatures` utility class. The `Signatures` class contains two public static methods for module and package signatures as well as two inner classes for type and member signatures. >> >> Signatures are rendered as `

Message-ID: On Thu, 26 Nov 2020 18:04:49 GMT, Jonathan Gibbons wrote: >> This PR adds a dedicated signature to module and package overview pages and moves all code for generating signatures to a new `doclets.formats.html.Signatures` utility class. The `Signatures` class contains two public static methods for module and package signatures as well as two inner classes for type and member signatures. >> >> Signatures are rendered as `

Message-ID: On Fri, 27 Nov 2020 16:33:27 GMT, Roger Riggs wrote: >> This change extends the functionality of the `@return` tag so that it can also be used as an inline tag in the first sentence of a description. >> >> The goal is to be able to simplify the following common pattern: >> >> /** >> * Returns the result. Optional additional text. >> * @return the result >> */ >> int method() { >> >> by >> >> /** >> * {@return the result} Optional additional text. >> */ >> int method() { >> >> Note: >> >> * The inline tag may only be used at the beginning of the description. A warning will be given if it is used elsewhere. >> * The expansion of the inline tag is `Returns " _content_ `.` where _content_ is the content of the tag. >> * If there is no block `@return` tag, the standard doclet will look for an inline tag at the beginning of the description >> * The inline tag can be inherited into overriding methods as if it was provided as a block tag. > > /** > * {@return the result} Optional additional text. > */ > ``` > The java source looks a bit odd/unusual because the "first sentence" does not appear to end with a period. > Though it seems like a convenience to include the '.' in the expansion, the source might be clearer if it did not, as in: > /** > * {@return the result}. Optional additional text. > */ > Similarly, prepending the "Returns", forces the verb, which is conventional but always the most appropriate word. > Changing the expansion to be only the contents of @ return would allow more flexible use. > It would put more responsibility on the developer to form the first sentence. (With "Returns"... and the "." outside the tag. @RogerRiggs I think that having to write `Returns {@return the result}.` would look more weird than the current proposal to omit the `.`. Note also that the proposed form matches the existing `{@summary ...}` tag which can be used to explicit define the "first sentence" that appears in summary tables. ------------- PR: https://git.openjdk.java.net/jdk/pull/1355 From hannesw at openjdk.java.net Fri Nov 27 17:45:17 2020 From: hannesw at openjdk.java.net (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=) Date: Fri, 27 Nov 2020 17:45:17 GMT Subject: RFR: JDK-8245058: improve presentation of annotations for modules and packages [v2] In-Reply-To: References: Message-ID: > This PR adds a dedicated signature to module and package overview pages and moves all code for generating signatures to a new `doclets.formats.html.Signatures` utility class. The `Signatures` class contains two public static methods for module and package signatures as well as two inner classes for type and member signatures. > > Signatures are rendered as `