Skip to content

Commit

Permalink
Improve FRAME storage docs (#1714)
Browse files Browse the repository at this point in the history 
This is a port (and hopefully a small improvement) of @kianenigma's PR
from the old Substrate repo:
paritytech/substrate#13987. Following #1689 I
moved the documentation of all macros relevant to this PR from
`frame_support_procedural` to `pallet_macros` while including a hint for
RA users.

Question: Again with respect to #1689: Is there a good reason why we
should *not* enhance paths with links to our current rustdocs? For
example, instead of
```rust
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::storage`.
```
we could write
```rust
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// [`frame_support::pallet_macros::storage`](https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.storage.html).
```
This results in a clickable link like this:
<img width="674" alt="image"
src="https://github.com/paritytech/polkadot-sdk/assets/10713977/c129e622-3942-4eeb-8acf-93ee4efdc99d">
I don't really expect the links to become outdated any time soon, but I
think this would be a great UX improvement over just having paths.

TODOs:
- [ ] Add documentation for `constant_name` macro
- [x] Add proper documentation for different `QueryKinds`, i.e.
`OptionQuery`, `ValueQuery`, `ResultQuery`. One example for each. Custom
`OnEmpty` should be moved to `QueryKinds` trait doc page.
- [ ] Rework `type_value` docs

---------

Co-authored-by: kianenigma <[email protected]>
  • Loading branch information
@wentelteefje @kianenigma
wentelteefje and kianenigma authored Nov 1, 2023
1 parent b2bb8cb commit b6965af
Show file tree
Hide file tree
Showing 10 changed files with 741 additions and 136 deletions.
30 changes: 17 additions & 13 deletions substrate/frame/bags-list/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,29 +13,33 @@ targets = ["x86_64-unknown-linux-gnu"]

[dependencies]
# parity
codec = { package = "parity-scale-codec", version = "3.6.1", default-features = false, features = ["derive"] }
scale-info = { version = "2.10.0", default-features = false, features = ["derive"] }
codec = { package = "parity-scale-codec", version = "3.6.1", default-features = false, features = [
"derive",
] }
scale-info = { version = "2.10.0", default-features = false, features = [
"derive",
] }

# primitives
sp-runtime = { path = "../../primitives/runtime", default-features = false}
sp-std = { path = "../../primitives/std", default-features = false}
sp-runtime = { path = "../../primitives/runtime", default-features = false }
sp-std = { path = "../../primitives/std", default-features = false }

# FRAME
frame-support = { path = "../support", default-features = false}
frame-system = { path = "../system", default-features = false}
frame-election-provider-support = { path = "../election-provider-support", default-features = false}
frame-support = { path = "../support", default-features = false }
frame-system = { path = "../system", default-features = false }
frame-election-provider-support = { path = "../election-provider-support", default-features = false }

# third party
log = { version = "0.4.17", default-features = false }
docify = "0.2.6"
aquamarine = { version = "0.3.2" }

# Optional imports for benchmarking
frame-benchmarking = { path = "../benchmarking", default-features = false , optional = true}
pallet-balances = { path = "../balances", default-features = false , optional = true}
sp-core = { path = "../../primitives/core", default-features = false , optional = true}
sp-io = { path = "../../primitives/io", default-features = false , optional = true}
sp-tracing = { path = "../../primitives/tracing", default-features = false , optional = true}
frame-benchmarking = { path = "../benchmarking", default-features = false, optional = true }
pallet-balances = { path = "../balances", default-features = false, optional = true }
sp-core = { path = "../../primitives/core", default-features = false, optional = true }
sp-io = { path = "../../primitives/io", default-features = false, optional = true }
sp-tracing = { path = "../../primitives/tracing", default-features = false, optional = true }

[dev-dependencies]
sp-core = { path = "../../primitives/core" }
Expand All @@ -46,7 +50,7 @@ frame-election-provider-support = { path = "../election-provider-support" }
frame-benchmarking = { path = "../benchmarking" }

[features]
default = [ "std" ]
default = ["std"]
std = [
"codec/std",
"frame-benchmarking?/std",
Expand Down
94 changes: 33 additions & 61 deletions substrate/frame/support/procedural/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -979,21 +979,26 @@ pub fn config(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

/// The `#[pallet::constant]` attribute can be used to add an associated type trait bounded by `Get`
/// from [`pallet::config`](`macro@config`) into metadata, e.g.:
///
/// ```ignore
/// #[pallet::config]
/// pub trait Config: frame_system::Config {
/// #[pallet::constant]
/// type Foo: Get<u32>;
/// }
/// ```
/// ---
///
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::constant`.
#[proc_macro_attribute]
pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

///
/// ---
///
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::constant_name`.
#[proc_macro_attribute]
pub fn constant_name(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

/// To bypass the `frame_system::Config` supertrait check, use the attribute
/// `pallet::disable_frame_system_supertrait_check`, e.g.:
///
Expand Down Expand Up @@ -1099,6 +1104,16 @@ pub fn compact(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

///
/// ---
///
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::call`.
#[proc_macro_attribute]
pub fn call(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

/// Each dispatchable may also be annotated with the `#[pallet::call_index($idx)]` attribute,
/// which explicitly defines the codec index for the dispatchable function in the `Call` enum.
///
Expand Down Expand Up @@ -1268,60 +1283,11 @@ pub fn generate_deposit(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

/// The `#[pallet::storage]` attribute lets you define some abstract storage inside of runtime
/// storage and also set its metadata. This attribute can be used multiple times.
///
/// Item should be defined as:
/// ---
///
/// ```ignore
/// #[pallet::storage]
/// #[pallet::getter(fn $getter_name)] // optional
/// $vis type $StorageName<$some_generic> $optional_where_clause
/// = $StorageType<$generic_name = $some_generics, $other_name = $some_other, ...>;
/// ```
///
/// or with unnamed generic:
///
/// ```ignore
/// #[pallet::storage]
/// #[pallet::getter(fn $getter_name)] // optional
/// $vis type $StorageName<$some_generic> $optional_where_clause
/// = $StorageType<_, $some_generics, ...>;
/// ```
///
/// I.e. it must be a type alias, with generics: `T` or `T: Config`. The aliased type must be
/// one of `StorageValue`, `StorageMap` or `StorageDoubleMap`. The generic arguments of the
/// storage type can be given in two manners: named and unnamed. For named generic arguments,
/// the name for each argument should match the name defined for it on the storage struct:
/// * `StorageValue` expects `Value` and optionally `QueryKind` and `OnEmpty`,
/// * `StorageMap` expects `Hasher`, `Key`, `Value` and optionally `QueryKind` and `OnEmpty`,
/// * `CountedStorageMap` expects `Hasher`, `Key`, `Value` and optionally `QueryKind` and `OnEmpty`,
/// * `StorageDoubleMap` expects `Hasher1`, `Key1`, `Hasher2`, `Key2`, `Value` and optionally
/// `QueryKind` and `OnEmpty`.
///
/// For unnamed generic arguments: Their first generic must be `_` as it is replaced by the
/// macro and other generic must declared as a normal generic type declaration.
///
/// The `Prefix` generic written by the macro is generated using
/// `PalletInfo::name::<Pallet<..>>()` and the name of the storage type. E.g. if runtime names
/// the pallet "MyExample" then the storage `type Foo<T> = ...` should use the prefix:
/// `Twox128(b"MyExample") ++ Twox128(b"Foo")`.
///
/// For the `CountedStorageMap` variant, the `Prefix` also implements
/// `CountedStorageMapInstance`. It also associates a `CounterPrefix`, which is implemented the
/// same as above, but the storage prefix is prepend with `"CounterFor"`. E.g. if runtime names
/// the pallet "MyExample" then the storage `type Foo<T> = CountedStorageaMap<...>` will store
/// its counter at the prefix: `Twox128(b"MyExample") ++ Twox128(b"CounterForFoo")`.
///
/// E.g:
///
/// ```ignore
/// #[pallet::storage]
/// pub(super) type MyStorage<T> = StorageMap<Hasher = Blake2_128Concat, Key = u32, Value = u32>;
/// ```
///
/// In this case the final prefix used by the map is `Twox128(b"MyExample") ++
/// Twox128(b"OtherName")`.
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::storage`.
#[proc_macro_attribute]
pub fn storage(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
Expand Down Expand Up @@ -1424,13 +1390,19 @@ pub fn type_value(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

///
/// ---
///
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::genesis_config`.
#[proc_macro_attribute]
pub fn genesis_config(_: TokenStream, _: TokenStream) -> TokenStream {
pallet_macro_stub()
}

///
/// ---
///
/// **Rust-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::genesis_build`.
#[proc_macro_attribute]
Expand Down
Loading

0 comments on commit b6965af

Please sign in to comment.