Skip to content

Commit

Permalink
Improve frame umbrella crate doc experience (paritytech#4007)
Browse files Browse the repository at this point in the history 
1. Add `#[doc(no_inline)]` to frame umbrella crate re-exports that
eventually resolve to `frame_support_procedural` so docs don't look like
the screenshot below and instead link to the proper `frame-support`
docs.
<img width="1512" alt="Screenshot 2024-04-05 at 20 05 01"
src="https://github.com/paritytech/polkadot-sdk/assets/16665596/a41daa4c-ebca-44a4-9fea-f9f336314e13">


2. Remove `"Rust-Analyzer Users: "` prefix from
`frame_support_procedural` doc comments, since these doc comments are
visible in the web documentation and possible to stumble upon especially
when navigating from the frame umbrella crate.

Co-authored-by: Kian Paimani <[email protected]>
  • Loading branch information
@liamaharon @kianenigma
liamaharon and kianenigma authored Apr 6, 2024
1 parent 9d62618 commit 74d6309
Show file tree
Hide file tree
Showing 2 changed files with 41 additions and 74 deletions.
14 changes: 7 additions & 7 deletions substrate/frame/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,24 +53,24 @@
#![cfg_attr(not(feature = "std"), no_std)]
#![cfg(feature = "experimental")]

/// Exports the main pallet macro. This can wrap a `mod pallet` and will transform it into
/// being a pallet, eg `#[polkadot_sdk_frame::pallet] mod pallet { .. }`.
///
/// Note that this is not part of the prelude, in order to make it such that the common way to
/// define a macro is `#[polkadot_sdk_frame::pallet] mod pallet { .. }`, followed by
/// `#[pallet::foo]`, `#[pallet::bar]` inside the mod.
#[doc(no_inline)]
pub use frame_support::pallet;

#[doc(no_inline)]
pub use frame_support::pallet_macros::{import_section, pallet_section};

/// The logging library of the runtime. Can normally be the classic `log` crate.
pub use log;

/// A list of all macros used within the main [`pallet`] macro.
/// Macros used within the main [`pallet`] macro.
///
/// Note: All of these macros are "stubs" and not really usable outside `#[pallet] mod pallet { ..
/// }`. They are mainly provided for documentation and IDE support.
///
/// To view a list of all the macros and their documentation, follow the links in the 'Re-exports'
/// section below:
pub mod pallet_macros {
#[doc(no_inline)]
pub use frame_support::{derive_impl, pallet, pallet_macros::*};
}

Expand Down
101 changes: 34 additions & 67 deletions substrate/frame/support/procedural/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -192,8 +192,7 @@ pub fn construct_runtime(input: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet`.
/// Documentation for this macro can be found at `frame_support::pallet`.
#[proc_macro_attribute]
pub fn pallet(attr: TokenStream, item: TokenStream) -> TokenStream {
pallet::pallet(attr, item)
Expand Down Expand Up @@ -290,8 +289,7 @@ pub fn transactional(attr: TokenStream, input: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::require_transactional`.
/// Documentation for this macro can be found at `frame_support::require_transactional`.
#[proc_macro_attribute]
pub fn require_transactional(attr: TokenStream, input: TokenStream) -> TokenStream {
transactional::require_transactional(attr, input)
Expand Down Expand Up @@ -450,8 +448,7 @@ pub fn __create_tt_macro(input: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::storage_alias`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::storage_alias`.
#[proc_macro_attribute]
pub fn storage_alias(attributes: TokenStream, input: TokenStream) -> TokenStream {
storage_alias::storage_alias(attributes.into(), input.into())
Expand Down Expand Up @@ -690,8 +687,7 @@ pub fn derive_impl(attrs: TokenStream, input: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::no_default`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::no_default`.
#[proc_macro_attribute]
pub fn no_default(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -700,8 +696,7 @@ pub fn no_default(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::no_default_bounds`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::no_default_bounds`.
#[proc_macro_attribute]
pub fn no_default_bounds(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand Down Expand Up @@ -784,7 +779,7 @@ pub fn register_default_impl(attrs: TokenStream, tokens: TokenStream) -> TokenSt
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// Documentation for this macro can be found at
/// `frame_support::pallet_prelude::inject_runtime_type`.
#[proc_macro_attribute]
pub fn inject_runtime_type(_: TokenStream, tokens: TokenStream) -> TokenStream {
Expand Down Expand Up @@ -822,8 +817,7 @@ fn pallet_macro_stub() -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::config`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::config`.
#[proc_macro_attribute]
pub fn config(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -832,8 +826,7 @@ pub fn config(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::constant`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::constant`.
#[proc_macro_attribute]
pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -842,8 +835,7 @@ pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::constant_name`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::constant_name`.
#[proc_macro_attribute]
pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -852,7 +844,7 @@ pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// Documentation for this macro can be found at
/// `frame_support::pallet_macros::disable_frame_system_supertrait_check`.
#[proc_macro_attribute]
pub fn disable_frame_system_supertrait_check(_: TokenStream, _: TokenStream) -> TokenStream {
Expand All @@ -862,8 +854,7 @@ pub fn disable_frame_system_supertrait_check(_: TokenStream, _: TokenStream) ->
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::storage_version`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::storage_version`.
#[proc_macro_attribute]
pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -872,8 +863,7 @@ pub fn storage_version(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::hooks`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::hooks`.
#[proc_macro_attribute]
pub fn hooks(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -882,8 +872,7 @@ pub fn hooks(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::weight`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::weight`.
#[proc_macro_attribute]
pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -892,8 +881,7 @@ pub fn weight(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::compact`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::compact`.
#[proc_macro_attribute]
pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -902,8 +890,7 @@ pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::call`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::call`.
#[proc_macro_attribute]
pub fn call(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -914,8 +901,7 @@ pub fn call(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::call_index`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::call_index`.
#[proc_macro_attribute]
pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -924,9 +910,7 @@ pub fn call_index(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
///
/// `frame_support::pallet_macros::feeless_if`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::feeless_if`.
#[proc_macro_attribute]
pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -935,9 +919,7 @@ pub fn feeless_if(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
///
/// `frame_support::pallet_macros::extra_constants`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::extra_constants`.
#[proc_macro_attribute]
pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -946,8 +928,7 @@ pub fn extra_constants(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::error`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::error`.
#[proc_macro_attribute]
pub fn error(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -956,8 +937,7 @@ pub fn error(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::event`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::event`.
#[proc_macro_attribute]
pub fn event(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -966,8 +946,7 @@ pub fn event(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::generate_deposit`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::generate_deposit`.
#[proc_macro_attribute]
pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -976,8 +955,7 @@ pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::storage`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::storage`.
#[proc_macro_attribute]
pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -986,8 +964,7 @@ pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::getter`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::getter`.
#[proc_macro_attribute]
pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -996,8 +973,7 @@ pub fn getter(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::storage_prefix`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::storage_prefix`.
#[proc_macro_attribute]
pub fn storage_prefix(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1006,8 +982,7 @@ pub fn storage_prefix(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::unbounded`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::unbounded`.
#[proc_macro_attribute]
pub fn unbounded(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1016,8 +991,7 @@ pub fn unbounded(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::whitelist_storage`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::whitelist_storage`.
#[proc_macro_attribute]
pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1026,7 +1000,7 @@ pub fn whitelist_storage(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// Documentation for this macro can be found at
/// `frame_support::pallet_macros::disable_try_decode_storage`.
#[proc_macro_attribute]
pub fn disable_try_decode_storage(_: TokenStream, _: TokenStream) -> TokenStream {
Expand All @@ -1036,8 +1010,7 @@ pub fn disable_try_decode_storage(_: TokenStream, _: TokenStream) -> TokenStream
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::type_value`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::type_value`.
#[proc_macro_attribute]
pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1046,8 +1019,7 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::genesis_config`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::genesis_config`.
#[proc_macro_attribute]
pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1056,8 +1028,7 @@ pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::genesis_build`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::genesis_build`.
#[proc_macro_attribute]
pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1066,8 +1037,7 @@ pub fn genesis_build(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::inherent`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::inherent`.
#[proc_macro_attribute]
pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1076,8 +1046,7 @@ pub fn inherent(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::validate_unsigned`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::validate_unsigned`.
#[proc_macro_attribute]
pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1086,8 +1055,7 @@ pub fn validate_unsigned(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::origin`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::origin`.
#[proc_macro_attribute]
pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand All @@ -1096,8 +1064,7 @@ pub fn origin(_: TokenStream, _: TokenStream) -> TokenStream {
///
/// ---
///
/// Rust-Analyzer Users: Documentation for this macro can be found at
/// `frame_support::pallet_macros::composite_enum`.
/// Documentation for this macro can be found at `frame_support::pallet_macros::composite_enum`.
#[proc_macro_attribute]
pub fn composite_enum(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand Down

0 comments on commit 74d6309

Please sign in to comment.