Crate document_features

Document your crate’s feature flags.

This crates provides a macro that extracts “documentation” comments from Cargo.toml

To use this crate, add #![doc = document_features::document_features!()] in your crate documentation. The document_features!() macro reads your Cargo.toml file, extracts feature comments and generates a markdown string for your documentation.

Basic example:

//! Normal crate documentation goes here.
//!
//! ## Feature flags
#![doc = document_features::document_features!()]

// rest of the crate goes here.

Documentation format:

The documentation of your crate features goes into Cargo.toml, where they are defined.

The document_features!() macro analyzes the contents of Cargo.toml. Similar to Rust’s documentation comments /// and //!, the macro understands comments that start with ## and #! . Note the required trailing space. Lines starting with ### will not be understood as doc comment.

## comments are meant to be above the feature they document. There can be several ## comments, but they must always be followed by a feature name or an optional dependency. There should not be #! comments between the comment and the feature they document.

#! comments are not associated with a particular feature, and will be printed in where they occur. Use them to group features, for example.

Examples:

This contents in Cargo.toml:

[package]
name = "..."
## ...

[features]
default = ["foo"]
##! This comments goes on top

### The foo feature enables the `foo` functions
foo = []

### The bar feature enables the bar module
bar = []

##! ### Experimental features
##! The following features are experimental

### Enable the fusion reactor
###
### ⚠️ Can lead to explosions
fusion = []

[dependencies]
document-features = "0.2"

##! ### Optional dependencies

### Enable this feature to implement the trait for the types from the genial crate
genial = { version = "0.2", optional = true }

### This awesome dependency is specified in its own table
[dependencies.awesome]
version = "1.3.5"
optional = true

Generates the following:

Preview

This comments goes on top foo (enabled by default) — The foo feature enables the foo functions bar — The bar feature enables the bar module Experimental features The following features are experimental fusion — Enable the fusion reactor ⚠️ Can lead to explosions Optional dependencies genial — Enable this feature to implement the trait for the types from the genial crate awesome — This awesome dependency is specified in its own table

 

Customization

You can customize the formatting of the features in the generated documentation by setting the key feature_label= to a given format string. This format string must be either a string literal or a raw string literal. Every occurrence of {feature} inside the format string will be substituted with the name of the feature.

For instance, to emulate the HTML formatting used by rustdoc one can use the following:

#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]

The default formatting is equivalent to:

#![doc = document_features::document_features!(feature_label = "**`{feature}`**")]

Compatibility

The minimum Rust version required to use this crate is Rust 1.54 because of the feature to have macro in doc comments. You can make this crate optional and use #[cfg_attr()] statements to enable it only when building the documentation: You need to have two levels of cfg_attr because Rust < 1.54 doesn’t parse the attribute otherwise.

#![cfg_attr(
    feature = "document-features",
    cfg_attr(doc, doc = ::document_features::document_features!())
)]

In your Cargo.toml, enable this feature while generating the documentation on docs.rs:

[dependencies]
document-features = { version = "0.2", optional = true }

[package.metadata.docs.rs]
features = ["document-features"]
## Alternative: enable all features so they are all documented
## all-features = true

Macros

document_features

Produce a literal string containing documentation extracted from Cargo.toml