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 only the [features] section. 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, and no other #! comments in between.

#! 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 = "..."
# ...

[dependencies]
document-features = "0.1"
# ...

[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
fusion = []

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

 

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.1", optional = true }

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

Macros

document_features