doc(kpm): correct stale backend docs + document KPM public API (#226) - #231
Merged
Conversation
First slice of the #226 documentation pass, covering the consumer-facing KPM/NFT surface. Fix docs that actively misled: - kpm/mod.rs described `ffi-backend` as "(default)" and pure-Rust as "(future)" — backwards since M9-3 (#142). Pure Rust is the default and needs no C++ toolchain; ffi-backend is opt-in for cross-validation. Rewrote the quick start around RustFreakMatcher with a real load -> kpm_matching -> get_pose flow, and added the missing `freak` and `rust_backend` rows to the module layout table. - lib.rs recommended `--features ffi-backend` for NFT marker generation; since #179 nft_marker_gen produces .iset + .fset + .fset3 entirely in pure Rust, so no C++ toolchain is needed. Fill the 22 missing_docs sites across the kpm tree (Point3d, Point2f/2i, FeaturePoint, HoughMatch, HoughSimilarityVoting fields, and the pyramid error-variant fields), and fix two broken intra-doc links in lib.rs / kpm/mod.rs (KpmRefDataSet path; feature-gated cpp_backend items). Add `#![warn(missing_docs)]` to kpm/mod.rs: the KPM tree is now at 100% rustdoc coverage, and CI's `clippy -D warnings` escalates the lint, so a new undocumented `pub` item there fails the build. Remaining modules (types.rs, ar2/tracking.rs, icp.rs) are tracked for later slices in #226. Refs #226 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
#226) The `#![warn(missing_docs)]` gate added to kpm/mod.rs fires on the bindgen output included into kpm_ffi's `bindings` module (34 errors under `--features ffi-backend`, escalated by CI's `clippy -D warnings`). Those items are generated verbatim from kpm_c_api.h by build.rs, so there is no source to attach rustdoc to. Add `#![allow(missing_docs)]` alongside the existing bindgen naming-lint allows in the same module, with a rationale. The module-level docs already describe the surface, and consumers are pointed at the safe CppFreakMatcher wrapper. Only surfaced in CI: this path needs --features ffi-backend, which cannot be built locally here (bindgen 0.72.1 panics on a 32-bit libclang vs a 64-bit target). Refs #226 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
kalwalt
added
documentation
…ilure (#226) Opting into `--features ffi-backend` (or `--all-features` / `dual-mode`) fails in build.rs with a bindgen panic — `assertion left == right failed`, `left: 4, right: 8` — when LIBCLANG_PATH points at a libclang built for a 32-bit target. The assertion prints the same triple on both sides, so the cause is not obvious from the message. A common trigger on Windows is a cross-compilation toolchain's libclang on LIBCLANG_PATH, e.g. the Xtensa clang from the esp-rs toolchain (32-bit ESP32). Add a Troubleshooting section covering the symptom, the cause, and the per-session fix (point LIBCLANG_PATH at an x86_64 libclang), plus why we don't ship a .cargo/config.toml [env] override (it would need force = true and has no per-OS conditionals, so it would break Linux CI). Also notes that the default build is pure Rust and needs no C++ toolchain at all — this only affects contributors who opt into the FFI backend. Refs #226 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
github-project-automation
Bot
moved this from In progress
to Done
in Plan to port KPM to rust
kalwalt
added a commit
that referenced
this pull request
Jul 20, 2026
The npm package (@webarkit/webarkitlib-wasm) shipped with no consumer-facing
usage guide — the README only said "see npm for API docs". Add a full
walkthrough at docs/wasm-js-integration.md covering:
- loading + initializing the module (init / init_wasm / init_panic_hook)
- the standard vs SIMD engines (the package `exports` map) + a runtime probe
- the three handles: WasmARHandle (square markers), WasmKpmHandle (NFT
detection), WasmNFTHandle (AR2 tracking)
- the NFT detect-then-track loop with the real serialized shapes
({ pose, page, error } and { found, matrix, error, cont_num })
- the 3x4 row-major pose-matrix layout, TypeScript usage, memory management
(free()), and common pitfalls (RGBA length, load-before-detect, etc.)
All snippets are checked against the actual crates/wasm/src/lib.rs API.
Link from the README's WASM section using an absolute GitHub URL so it also
works for consumers reading the README on npmjs.com (only README.md is
published to the package, not docs/). The root README is the source copied
to pkg/README.md by build-dual at build time; pkg/README.md refreshes on the
next `npm run build`.
Second slice of the #226 documentation pass (after the KPM rustdoc slice in
#231).
Refs #226
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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.
First slice of #226, covering the consumer-facing KPM/NFT surface. #226 stays open — the remaining modules are listed below.
The important part: docs that actively misled
Two places documented the pre-M9-3 world and told users the wrong thing:
kpm/mod.rsdescribedffi-backendas "(default)" and pure-Rust as "(future)" — backwards since M9-3 (feat(kpm): M9-3 - remove FFI as default, pure Rust backend complete #142). Pure Rust is the default and needs no C++ toolchain;ffi-backendis opt-in for cross-validation. The quick start also built aCppFreakMatcher.lib.rsrecommended--features ffi-backendfor NFT marker generation (spotted by @kalwalt in the rendered docs). Since feat(example): wire nft_marker_gen to RustFreakMatcher for .fset3 generation #179,nft_marker_genproduces.iset+.fset+.fset3entirely in pure Rust — no C++ toolchain needed.Both now match reality. The quick start is a real
RustFreakMatcher→set_ref_data_set→kpm_matching→get_poseflow, pointing atsimple_nftandWasmKpmHandle; the module-layout table gained the missingfreakandrust_backendrows.Also in this slice
missing_docssites filled across thekpmtree:Point3d,Point2f/Point2i,FeaturePoint,HoughMatch,HoughSimilarityVotingfields, and the pyramid error-variant fields.kpm::KpmRefDataSet::generate→kpm::types::KpmRefDataSet::generate, and the feature-gatedcpp_backend/CppFreakMatcherlinks (unresolvable withoutffi-backend).#![warn(missing_docs)]onkpm/mod.rs— the KPM tree is now at 100% rustdoc coverage, and CI'sclippy -D warningsescalates the lint, so a new undocumentedpubitem in KPM fails the build.Remaining for #226 (later slices)
types.rsC-port struct fieldsar2/tracking.rs+icp.rs#![warn(missing_docs)]+ the 43 remaining broken intra-doc linksCrate-wide
missing_docswent 358 → 336;lib.rsandkpm/**are now doc-warning free.Verification
cargo doc— no warnings originating in any touched filecargo fmt --checkclean;clippy --all-targets --features simd,log-helpers -D warningscleancargo test --lib— 432 passed🤖 Generated with Claude Code