Attribute Macro doc_replace

#[doc_replace]

Replaces placeholders in rustdoc doc comments.

The purpose of this macro is to enable us to extract boilerplate, while at the same time let rustfmt format code blocks. This macro rewrites the whole documentation of the annotated item.

Replacements can be placed in the documentation as # {placeholder}. Each replacement must be its own line, it’s not possible to place a placeholder in the middle of a line. The before_snippet and after_snippet placeholders are expanded to the esp_hal::before_snippet!() and esp_hal::after_snippet!() macros, and are expected to be used in example code blocks.

You can also define custom replacements in the attribute. A replacement can be an unconditional literal (i.e. a string that is always substituted into the doc comment), or a conditional.

Examples

#[doc_replace(
  "literal_placeholder" => "literal value",
  "conditional_placeholder" => {
    cfg(condition1) => "value 1",
    cfg(condition2) => "value 2",
    _ => "neither value 1 nor value 2",
  }
)]
/// Here comes the documentation.
///
/// The replacements are interpreted outside of code blocks, too:
/// # {literal_placeholder}
///
/// ```rust, no run
/// // here is some code
/// # {literal_placeholder}
/// // here is some more code
/// # {conditional_placeholder}
/// ```
fn my_function() {}