Repository navigation
Conversation
Adds api-reference/java-api, a standalone project that generates the Javadoc site for the official Java SDK (org.zvec:zvec-java) into public/api-reference/java/, mirroring how the Python (mkdocs) and Node.js (typedoc) references are built. - build.sh resolves the latest release from Maven metadata, downloads the -sources.jar, drops the examples package and runs javadoc. - The org.bytedeco:javacpp artifact the JNI bindings are annotated with is put on the classpath: javadoc 9+ reports unresolved symbols as errors. - Output is pinned to English via -J-Duser.language/-J-Duser.country so host locale cannot leak into the generated UI. - Javadoc 11 dropped frame-based output, so the script requires JDK 17+ and prefers 21 to match CI (setup-java temurin 21). - Adds the Java card to /api-reference (en/zh), mentions Java in llms.txt and builds the reference in both website workflows.
|
☁️ Cloudflare Pages preview: https://9abb3233.zvec-web.pages.dev |
Doc comments that contain raw angle brackets (the JNI bindings mention C++ types such as std::shared_ptr<zvec::Collection>*) are not valid HTML, so javadoc replaces the offending character with a marker span and renders it in the page: "Internally maps to std::shared_ptr invalid input: '<' zvec::Collection>*". Replace the marker with the character javadoc reported. The surrounding text is already escaped correctly, so the comment reads as intended again. Logs how many markers were restored and warns if any invalid-tag markup survives, so a future change to the marker format cannot fail silently.
JavaCPP copies the Doxygen comments of zvec/c_api.h verbatim into the
generated bindings, and javadoc renders whatever it cannot parse:
- a raw '<' that cannot start an HTML tag (std::shared_ptr<zvec::Collection>*)
makes javadoc emit "invalid input: '<'" and print that marker in the page;
- commands javadoc does not know (\brief, \note) are printed literally, which
leaked "\brief" into the generated pages.
Fix both at the source instead of patching the output:
scripts/clean_doc_comments.py rewrites the doc comments of the downloaded
sources before javadoc runs. It only touches /** ... */ comments, skips string
and char literals (the sources contain a "\u2014" message), and leaves
{@code ...} / {@link ...} spans alone because javadoc already escapes their
content.
javadoc warnings for zvec-java 0.7.0 drop from 6 "invalid input" to 0, and the
marker repair from the previous commit now reports "Restored 0" and stays as a
fallback. The two remaining "@PARAM ... is not a parameter name" warnings are
upstream: c_api.h documents a deleted_count parameter that
zvec_collection_delete_by_filter does not take, and JavaCPP renames the capacity
parameter of zvec_byte_array_create to _capacity.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add the Java API reference, following the same pattern as the Python (mkdocs) and Node.js (typedoc) references: a standalone source project under
api-reference/java-api/that builds static HTML intopublic/api-reference/java/.api-reference/java-api/build.sh— resolves the latestorg.zvec:zvec-javarelease from Maven metadata (ZVEC_JAVA_VERSIONpins it), downloads the-sources.jar, dropsorg.zvec.binding.examples(guides, not API surface), runsjavadoc, then injects the site favicon andstyles/extra.cssfor light brandingapp/[lang]/(home)/api-reference/page.tsx— Java card (en/zh) linking to/api-reference/java/app/llms.txt/route.ts— mentions the Java referencejava-apibuild.gitignore— generated output plus the local build dirOutput: 182 HTML pages covering
org.zvec.binding(74 types) andorg.zvec.binding.presets, 4.6 MB, gitignored and built in CI like the other two references.Notes on the javadoc invocation
org.bytedeco.javacpptypes. Javadoc 9+ reports unresolved symbols as errors, so without that dependency the build fails with 100 errors on any modern JDK. The script readsjavacpp.versionfrom thezvec-javaPOM and downloads the matching jar (1.5.11 for 0.7.0); warnings drop from 100 to 8, all pre-existing doc-comment nits in the SDK sources.-J-Duser.language=en -J-Duser.country=US. Building on a machine with a non-English locale otherwise yields a localized javadoc UI (e.g. Chinese navigation labels).-localewas not an option here because JDK 8 requires it to be the first argument.$JAVADOC→ 21 → 17+ → PATH), erroring out below 17 so local output matches what gets deployed.Tested locally
./build.shexits 0 on JDK 21; no generated file contains CJK characters;index.htmlis the HTML5 overview page (no frameset)next devserves/api-reference/java/index.html, class pages andzvec-extra.csswith 200, and the Java card renders on both/en/api-reference/and/zh/api-reference/python3 -m http.serverresolves the directory route/api-reference/java/(next devdoes not do directory-index routing forpublic/, same as the existing python/nodejs references)