From 82d9d5adcf3f419bc454ef73fc4b4569c70f4f44 Mon Sep 17 00:00:00 2001 From: Andrew Jones Date: Mon, 25 Jan 2021 17:18:38 +0000 Subject: [PATCH] Pallet proc macro doc improvements (#7955) * Fix weight syntax in comments * Mention to add `IsType` bound * Link to subsee * Fix link * Update frame/support/procedural/src/pallet/parse/call.rs Co-authored-by: David * Apply review suggestion from @dvdplm, make StorageInstance doc link * fix ui test Co-authored-by: David Co-authored-by: thiolliere --- .../support/procedural/src/pallet/parse/call.rs | 4 ++-- substrate/frame/support/src/lib.rs | 13 ++++++++----- .../test/tests/pallet_ui/call_missing_weight.stderr | 2 +- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/substrate/frame/support/procedural/src/pallet/parse/call.rs b/substrate/frame/support/procedural/src/pallet/parse/call.rs index 514dc9203e..880cf54f8b 100644 --- a/substrate/frame/support/procedural/src/pallet/parse/call.rs +++ b/substrate/frame/support/procedural/src/pallet/parse/call.rs @@ -57,7 +57,7 @@ pub struct CallVariantDef { } /// Attributes for functions in call impl block. -/// Parse for `#[pallet::weight = expr]` +/// Parse for `#[pallet::weight(expr)]` pub struct FunctionAttr { weight: syn::Expr, } @@ -175,7 +175,7 @@ impl CallDef { if call_var_attrs.len() != 1 { let msg = if call_var_attrs.is_empty() { - "Invalid pallet::call, require weight attribute i.e. `#[pallet::weight = $expr]`" + "Invalid pallet::call, requires weight attribute i.e. `#[pallet::weight($expr)]`" } else { "Invalid pallet::call, too many weight attributes given" }; diff --git a/substrate/frame/support/src/lib.rs b/substrate/frame/support/src/lib.rs index 298fbdc321..08852a7f3c 100644 --- a/substrate/frame/support/src/lib.rs +++ b/substrate/frame/support/src/lib.rs @@ -1388,8 +1388,9 @@ pub mod pallet_prelude { /// ### Macro expansion /// /// For each storage item the macro generates a struct named -/// `_GeneratedPrefixForStorage$NameOfStorage`, implements `StorageInstance` on it using the -/// pallet and storage name. It then uses it as the first generic of the aliased type. +/// `_GeneratedPrefixForStorage$NameOfStorage`, and implements [`StorageInstance`](traits::StorageInstance) +/// on it using the pallet and storage name. It then uses it as the first generic of the aliased +/// type. /// /// /// The macro implements the function `storage_metadata` on `Pallet` implementing the metadata for @@ -1909,7 +1910,8 @@ pub mod pallet_prelude { /// ``` /// 5. **migrate Config**: move trait into the module with /// * all const in decl_module to `#[pallet::constant]` -/// 6. **migrate decl_module**: write: +/// * add bound `IsType<::Event>` to `type Event` +/// 7. **migrate decl_module**: write: /// ```ignore /// #[pallet::hooks] /// impl Hooks for Pallet { @@ -1996,8 +1998,9 @@ pub mod pallet_prelude { /// /// ## Checking upgrade guidelines: /// -/// * compare metadata. This checks for: -/// * call, names, signature, doc +/// * compare metadata. Use [subsee](https://github.com/ascjones/subsee) to fetch the metadata +/// and do a diff of the resulting json before and after migration. This checks for: +/// * call, names, signature, docs /// * event names, docs /// * error names, docs /// * storage names, hasher, prefixes, default value diff --git a/substrate/frame/support/test/tests/pallet_ui/call_missing_weight.stderr b/substrate/frame/support/test/tests/pallet_ui/call_missing_weight.stderr index f499e8a65d..37386d7771 100644 --- a/substrate/frame/support/test/tests/pallet_ui/call_missing_weight.stderr +++ b/substrate/frame/support/test/tests/pallet_ui/call_missing_weight.stderr @@ -1,4 +1,4 @@ -error: Invalid pallet::call, require weight attribute i.e. `#[pallet::weight = $expr]` +error: Invalid pallet::call, requires weight attribute i.e. `#[pallet::weight($expr)]` --> $DIR/call_missing_weight.rs:17:3 | 17 | fn foo(origin: OriginFor) -> DispatchResultWithPostInfo {}