patpatpat123 opened a new pull request, #393: URL: https://github.com/apache/maven-jxr/pull/393
Hi! This is my take on #209 (JXR-152): Javadoc dropped frames in Java 13 and got a search box, and JXR should be able to do the same. Jesper wrote back then that it was "not entirely trivial", and he was right, so I tried to keep it as small and as boring to review as I could. **What you get.** With `javadocVersion` 13 or later the report has no frames. Every page, the source pages included, has a navigation bar (Overview, Package, All Classes) with a search box in it. The box finds packages and classes by name: exact matches first, then names that start with what you typed, camel case (`JCT` finds `JavaCodeTransform`), then names that merely contain it. Nested classes are found by their own name, a query with a dot matches the qualified name, and the arrow keys, Enter and Escape do what you expect. Without JavaScript there is simply no box, and the new "All Classes" page does the job. `index.html` is the overview now, and `overview-summary.html` redirects to it, so old links keep working. Source pages and their line anchors are where they always were. **How.** There is a new template set, `templates/jdk13`, picked by the same ladder as the other sets. It reuses the markup and the CSS classes of the Java 8 set, so it looks like what people know. `DirectoryIndexer` writes `search-index.js` from the model it already has and puts a small `search.js` next to it, and `JavaCodeTransform` gives the source pages their navigation bar. The only new public method is `JXR.setFrames(boolean)`; it defaults to `true`, and with frames nothing changes. The issue suggests reusing the search files that Javadoc generates. I did not, and I owe you the reason: they only exist if Javadoc ran, and ran before JXR; their format and script changed from release to release and long needed jQuery; they list the documented API only, while the xref also has private and test classes; and their links go to members, which have no anchors in our pages. Writing an index of our own turned out to be less code than making all of that fit. `search.js` is written from scratch for this PR. There is no Javadoc or jQuery code in it, only the keys of the index (`p`, `l`, `u`) follow Javadoc's. **Four things you may want differently** - The default changes for builds that run on Java 13 or later, because `javadocVersion` follows the Java version of the build, as it always did. `<javadocVersion>1.8</javadocVersion>` brings the frames back, custom templates (`templateDir`) keep them anyway, and the usage page explains it. - I took 13 as the threshold because the issue says so and because that is where Javadoc removed frames. As far as I know Javadoc already stopped generating them by default in 11, so 11 would be just as defensible. It is one token to change. - `@since 3.7.0`, and the same number on the usage page, assume that the next release is a minor one. - There is no new style sheet. 13 and later already got `jdk8/stylesheet.css`, so the rules for the search box went to the end of that file rather than into one more copy of it. **Left out on purpose** - Pages of classes in the default package link their style sheet one level too high today (`JXR141Test` pins `..//Test141.html`), and the new navigation bar inherits that. I would rather fix it in a PR of its own. - A search hit for a nested class opens the outer class at the top, like the class lists do today, because there is no `Outer.Inner` anchor. - Search for members, which the model does not know, and ARIA attributes for the result list. Both would make nice follow-ups. **Testing.** New unit tests cover the index (content and escaping), the set of pages with and without frames, the navigation bar of the source pages, and in the plugin the versions 13, 12 (still frames) and 13 with own templates (still frames). There is a new IT, `JXR-152_search`. `mvn -Prun-its verify` passes on Java 17 and 25; I have no Java 8 at hand, so I kept to its API and count on CI for that one. The script is the part the build cannot test, as there is no JavaScript engine to run it with. I ran its matching, ranking and key handling against a stubbed page in Node, and went through generated reports in a Chromium browser, one of them with 6,000 classes in the index. I did not try Firefox or Safari. Fixes #209 --- To make clear that you license your contribution under the [Apache License Version 2.0, January 2004](https://www.apache.org/licenses/LICENSE-2.0) check one of the following: - [ ] I hereby declare this contribution to be licensed under the [Apache License Version 2.0, January 2004](https://www.apache.org/licenses/LICENSE-2.0) - [ ] I hereby declare that I have filed an [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf). 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
