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

In-line replacements can be placed in the middle of a line as __placeholder__. A line may contain any number of them. Should the replacements be conditional, the line is emitted for every combination of their values.

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.

A replacement does not have to be a literal: anything that expands to a string literal works, such as a call to a macro generated by esp-metadata. Lines containing such a replacement are assembled with concat!, which means the value only needs to be valid for the configuration the documentation is built for.

Examples

#[doc_replace(
  "literal_placeholder" => "literal value",
  "generated_placeholder" => gpio_for_signal!(USB_FS_DP),
  "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}
///
/// The macro even supports __conditional_placeholder__ replacements in-line.
/// ```
fn my_function() {}