document-features
A Rust proc-macro that turns Cargo.toml feature comments into rendered crate documentation.
Repository Health
Technical Analysis
document-features is a Rust procedural macro that keeps your crate’s feature-flag documentation next to the feature definitions themselves. You write ordinary comments above each feature in Cargo.toml, and the macro reads them at compile time to generate a Markdown block for your rustdoc output.
Maintained by the Slint team and used by a huge number of crates (over 116 million downloads), it eliminates the drift between what features exist and how they are documented, since both live in the same place.
What You Get
- A
document_features!()macro that generates a Markdown feature list from your Cargo.toml ##comments to document individual features inline with their definitions#!comments to add section headings and explanatory prose between features- Intra-doc link support so feature docs can reference items elsewhere in your crate
- Zero runtime cost, since everything happens at compile time during macro expansion
Common Use Cases
- Auto-generating a Cargo features section in a library’s crate-level rustdoc
- Keeping feature documentation in sync with feature definitions in one file
- Grouping experimental or optional features under documented headings
- Publishing accurate feature docs to docs.rs without maintaining a separate list
Under The Hood
Architecture - The whole crate is a single proc-macro in lib.rs (~1,000 lines). The #[proc_macro] document_features entry point locates and reads the caller’s Cargo.toml, walks the [features] table while collecting the preceding ## and #! doc comments, and assembles a Markdown string that it returns as a string-literal TokenStream for rustdoc to embed. Tech Stack - Rust 2018 edition (MSRV 1.56), declared as a proc-macro = true library, with litrs as its only dependency for parsing literal tokens; it relies on the built-in proc_macro crate for token manipulation. Code Quality - The parser is carefully written to handle quoting, escaping, and section grouping, and the repository ships integration tests (including a self-documentation test) that verify the generated Markdown. API Design - The public surface is a single macro with no arguments in the common case, so adoption is one attribute line plus ordinary comments in Cargo.toml, keeping the mental model minimal.
