Skip to content

docs: clarify rache's API model - #11

Merged
tisonkun merged 3 commits into
mainfrom
codex/document-capability-map
Sep 2, 2026
Merged

docs: clarify rache's API model#11
tisonkun merged 3 commits into
mainfrom
codex/document-capability-map

Conversation

@tisonkun

@tisonkun tisonkun commented Sep 2, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add a caller-oriented API model that explains one-shot functions, incremental states, std::io::Write, Hasher, and BuildHasher.
  • Add a complete algorithm capability map to both the README and crate documentation, including the deliberate CityHash and 128-bit adapter gaps.
  • Make each algorithm-family module independently explain its variants, configuration, integration boundaries, limitations, and basic usage.
  • Present public modules and configured constructors before crate-private implementation details in source.

Design Notes

This follows the strongest documentation pattern shared by AsyncBand and DataSketches: establish project scope, give users a task-oriented map, then make each module useful when reached directly from docs.rs. Existing APIs remain unchanged.

Associated oneshot methods are retained and documented as namespaced delegates to the module-level functions. Although they duplicate the free-function surface, removing them would trade a modest reduction in API size for a real discoverability and compatibility cost without evidence of caller harm.

No changelog entry is included because the changes do not alter supported or observable behavior.

Validation

  • cargo x lint
  • cargo x check
  • cargo x test

Source readers currently encounter crate-private byte helpers before the four public families, and XXH32/XXH64 order their one-shot convenience method before the configured constructor. Put the public surface first and use the same constructor-first method order as the other streaming states.
The existing family summary does not explain how one-shot functions, incremental states, std::io::Write, Hasher, and BuildHasher relate. Give callers a single capability map, explain why 128-bit and CityHash variants have fewer adapters, and distinguish namespaced one-shot conveniences from separate hashing modes.
Users often land on a family module directly from docs.rs. Describe each family's variants, configuration, streaming and hash-table capabilities, important limitations, and a minimal runnable example without requiring the crate overview as prior context.
@tisonkun
tisonkun marked this pull request as ready for review September 2, 2026 08:01
@tisonkun
tisonkun merged commit cd532db into main Sep 2, 2026
10 checks passed
@tisonkun
tisonkun deleted the codex/document-capability-map branch September 2, 2026 08:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant