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]

Reply via email to