Repository: paritytech/substrate
File: frame/support/procedural/src/lib.rs (Rust)

Code before:
/// ```
///
/// The runtime metadata for this pallet contains the following
///  - " Documentation for pallet 1" (captured from `///`)
///  - "Documentation for pallet 2"  (captured from `#[doc]`)
///  - content of ../README.md       (captured from `#[doc]` with `include_str!`)
///  - content of "../doc1.md"       (captured from `pallet_doc`)
///  - content of "../doc1.md"       (captured from `pallet_doc`)
///
/// ### `doc` attribute
///
/// The value of the `doc` attribute is included in the runtime metadata, as well as
/// expanded on the pallet module. The previous example is expanded to:
///
/// ```ignore
/// /// Documentation for pallet 1
/// /// Documentation for pallet 2
/// /// Content of README.md
/// pub struct Pallet<T>(_);
/// ```
///
/// ### `pallet_doc` attribute
///
/// The `pallet_doc` attribute can only be provided with one argument,
/// which is the file path that holds the documentation to be added to the metadata.
///
/// Unlike the `doc` attribute, the documentation provided to the `proc_macro` attribute is
/// not inserted at the beginning of the module.
#[proc_macro_attribute]
pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream {
	pallet::pallet(attr, item)
}

/// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will
/// designate that module as a benchmarking module.
///
/// See `frame_benchmarking::v2` for more info.
#[proc_macro_attribute]
pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream {
	match benchmark::benchmarks(attr, tokens, false) {
		Ok(tokens) => tokens,
		Err(err) => err.to_compile_error().into(),
	}
}

/// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will
/// designate that module as an instance benchmarking module.
///
/// See `frame_benchmarking::v2` for more info.
#[proc_macro_attribute]
pub fn instance_benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream {

Review comment (refactor):
Basti wrote

> we probably should settle with having on #![doc = include_str!("../README.md")] at the top of lib.rs and then some special pallet_docs("../README.md") attribute for the frame macros (otherwise the docs would be duplicated in the crate).

Personally, I don't understand that by the documentation in this PR. Can you elaborate a bit why both `doc` and `pallet_doc` are needed in the examples or something.

It could be just me though... :)


Code after:
/// ```
///
/// The runtime metadata for this pallet contains the following
///  - " Documentation for pallet 1" (captured from `///`)
///  - "Documentation for pallet 2"  (captured from `#[doc]`)
///  - content of ../README.md       (captured from `#[doc]` with `include_str!`)
///  - content of "../doc1.md"       (captured from `pallet_doc`)
///  - content of "../doc2.md"       (captured from `pallet_doc`)
///
/// ### `doc` attribute
///
/// The value of the `doc` attribute is included in the runtime metadata, as well as
/// expanded on the pallet module. The previous example is expanded to:
///
/// ```ignore
/// /// Documentation for pallet 1
/// /// Documentation for pallet 2
/// /// Content of README.md
/// pub struct Pallet<T>(_);
/// ```
///
/// If you want to specify the file from which the documentation is loaded, you can use the
/// `include_str` macro. However, if you only want the documentation to be included in the
/// runtime metadata, use the `pallet_doc` attribute.
///
/// ### `pallet_doc` attribute
///
/// Unlike the `doc` attribute, the documentation provided to the `pallet_doc` attribute is
/// not inserted on the module.
///
/// The `pallet_doc` attribute can only be provided with one argument,
/// which is the file path that holds the documentation to be added to the metadata.
///
/// This approach is beneficial when you use the `include_str` macro at the beginning of the file
/// and want that documentation to extend to the runtime metadata, without reiterating the
/// documentation on the module itself.
#[proc_macro_attribute]
pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream {
	pallet::pallet(attr, item)
}

/// An attribute macro that can be attached to a (non-empty) module declaration. Doing so will
/// designate that module as a benchmarking module.
///
/// See `frame_benchmarking::v2` for more info.
#[proc_macro_attribute]
pub fn benchmarks(attr: TokenStream, tokens: TokenStream) -> TokenStream {
	match benchmark::benchmarks(attr, tokens, false) {
		Ok(tokens) => tokens,
		Err(err) => err.to_compile_error().into(),
	}