Attribute Macro docs_const

Source

#[docs_const]

Expand description

Macro to extract the documentation on any item that accepts doc comments and store it in a const variable.

By default, this const variable inherits visibility from its parent item. This can be manually configured; see configuration section below.

§Examples

use documented::docs_const;

/// This is a test function
#[docs_const]
fn test_fn() {}

assert_eq!(TEST_FN_DOCS, "This is a test function");

§Configuration

With the customise feature enabled, you can customise this macro’s behaviour using attribute arguments.

Currently, you can:

§1. set a custom constant visibility like so:

mod submodule {
    /// Boo!
    #[docs_const(vis = pub)]
    struct Wooooo;
}

// notice how the constant can be seen from outside
assert_eq!(submodule::WOOOOO_DOCS, "Boo!");

§2. set a custom constant name like so:

/// If you have a question raise your hand
#[docs_const(rename = "DONT_RAISE_YOUR_HAND")]
mod whatever {}

assert_eq!(DONT_RAISE_YOUR_HAND, "If you have a question raise your hand");

§3. set a default value when doc comments are absent like so:

use documented::docs_const;

#[docs_const(default = "In this position many of you blunder.")]
trait StartingPosition {}

assert_eq!(
    STARTING_POSITION_DOCS,
    "In this position many of you blunder."
);

This option is primarily designed for DocumentedFields and DocumentedVariants, so it’s probably not very useful here. But it could conceivably come in handy in some niche meta-programming contexts.

§4. disable line-trimming like so:

///     This is a test constant
#[docs_const(trim = false)]
const test_const: u8 = 0;

assert_eq!(TEST_CONST_DOCS, "     This is a test constant");

Multiple option can be specified in a list like so: name = "FOO", trim = false.

If there are other configuration options you wish to have, please submit an issue or a PR.

docs_const