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.56. 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