read-doc 0.1.0

Macro to read module documentation from Rust source files
Documentation

Macro to read module documentation from Rust source files

docs.rs Crates.io Rust version 1.88+

//! # Overall module documentation
#![doc = read_doc::module!("submodule1.rs", "submodule2.rs")]

mod submodule1;
mod submodule2;

The read_doc::module!("path1.rs", ...) macro reads module documentation from Rust source files as a string.

This is useful if you want to arrange your code logically in private submodules along with summary module documentation, then re-export the items and overview documentation in the public parent module.

Example

The following documentation for the fruit module will be generated from the three files below.

## Fruit functionality

This has a lot of interesting functionality.

### Apple processing

Green or red, we don't care.

### Orange processing

Various orange-related code.

/src/fruit/mod.rs

//! ## Fruit functionality
//!
//! This has a lot of interesting functionality.
#![doc = read_doc::module!("apple.rs", "orange.rs")]

mod apple;
pub use apple::*;

mod orange;
pub use orange::*;

/src/fruit/apple.rs

//! ### Apple processing
//!
//! Green or red, we don't care.

/// Sweet or tart.
pub struct Apple;

/src/fruit/orange.rs

//! ### Orange processing
//!
//! Various orange-related code.

/// A round fruit.
pub struct Orange;

Similar crates

I found three crates that allow access to doc comments on types at runtime. I have not tried them, but here they are, listed in order of most to least simple:

  1. documented
  2. doc_for
  3. user_doc

Minimum supported Rust version

Currently the minimum supported Rust version (MSRV) is 1.88. Future increases in the MSRV will require a major version bump.

Development

This is in active development. I am open to suggestions.

LLM use

LLM produced code must be marked in the commit message. I typically ask the LLM to make its own commits, then I make my own changes after careful review.

Example: 62ab2857d8d17fdf2d7db1f902b6281732854648 was written by Claude; I cleaned up that commit in 63e1a97c17f4c9452d59309c1e26a226f1155009.

License

Unless otherwise noted, this project is dual-licensed under the Apache 2 and MIT licenses. You may choose to use either.

Contributions

Unless you explicitly state otherwise, any contribution you submit as defined in the Apache 2.0 license shall be dual licensed as above, without any additional terms or conditions.