cargo-derive-doc

what

cargo-derive-doc analyzes macro expansions and documents what impls and items the macro expands to

// <generated by cargo-derive-doc>
// Macro expansions:
//   pub enum MediaError
//   impl core::error::Error for MediaError
//   impl core::fmt::Display for MediaError
//   impl From<DownloadError> for MediaError
//   impl From<BookParsingError> for MediaError
// </generated by cargo-derive-doc>
error_set! {
    MediaError = DownloadError || BookParsingError;
    // ...
}

supports #[derive()] attributes and function-like macros that generate significant code.

status

minimally tested, seems to work. still at the basic proof of concept stage, likely buggy. don't be too surprised if it makes incorrect edits you have to roll back.

usage

TODO: add to this repo's nix flake

# install
cargo install --git https://github.com/LunNova/x.git --bin cargo-derive-doc

# document all macro invocations in your workspace
cargo derive-doc --all-targets

# document only examples/
cargo derive-doc --examples --dir-filter examples/

# see what would change without writing
cargo derive-doc --dry-run --examples

runs as a rustc wrapper to capture macro expansions, then diffs original vs expanded code to identify what each macro generates.

what it documents

• derive macros (#[derive(Debug, Clone)])
• function-like macros (error_set!, pattern_wishcast!, etc.)
• filters out well-known builtin derives (Debug, Clone, Copy impls)

how it works

1. runs your code through rustc -Zunpretty=expanded to get fully expanded source
2. diffs original vs expanded to find what each macro generated
3. associates generated code with macro calls using text diffing
4. adds/updates comment blocks above macro invocations
5. cleans up old comments when macros are removed

limitations

• requires nightly rust (uses -Zunpretty=expanded)
• currently associates all generated items with every function-like macro (see FIXME in source)
• only processes top-level macro invocations (no indented ones)
• may miss some edge cases in complex macro interactions

examples

see examples/ for demo files showing the tool in action:

• error_set_test.rs - function-like macro documentation
• obvious_doesnt_doc.rs - shows filtering of basic derives