improve FRAME storage docs #13987
improve FRAME storage docs #13987
Conversation
kianenigma
added
the
I6-documentation
| /// } | ||
| /// ``` | ||
| #[proc_macro_attribute] | ||
| pub fn constant(_: TokenStream, _: TokenStream) -> TokenStream { | ||
| pallet_macro_stub() | ||
| } | ||
|
|
||
| /// Declares an implementation block to be the dispatchable portion of a pallet. In other words, |
There was a problem hiding this comment.
| /// Declares an implementation block to be the dispatchable portion of a pallet. In other words, | |
| /// Declares an implementation block to be the callable portion of a pallet. In other words, |
I see below that the trait Dispatchable shows up, but my initial intuition was to leave this word out of the docs. People understand callable. Dispatchable less so.
| /// | ||
| /// #[pallet::call] | ||
| /// impl<T: Config> Pallet<T> { | ||
| /// fn do_stuff(_origin: OriginFor<T>, arg: u32) { |
There was a problem hiding this comment.
Is weight no longer required? I think that is a good thing, but was surprised there wasn't dev mode stuff going on
There was a problem hiding this comment.
It might be worth noting in the docs what call functions require? For example, it seems they all require an origin as the first argument.
There was a problem hiding this comment.
in dev_mode it should no longer be needed.
There was a problem hiding this comment.
See #14115 for exactly what you said about call.
| /// # use frame_support::pallet_prelude::*; | ||
| /// # #[pallet::config] | ||
| /// # pub trait Config: frame_system::Config {} | ||
| /// # #[pallet::pallet] | ||
| /// # pub struct Pallet<T>(_); | ||
| /// #[pallet::storage] |
There was a problem hiding this comment.
whats going on here with extra hashtags?
There was a problem hiding this comment.
It will hide this line in the generated rust-docs. Try cargo doc to see examples.
| /// | ||
| /// If the keys are not trusted (e.g. can be set by a user), a cryptographic `hasher` | ||
| /// such as `blake2_128_concat` must be used for the key hashers. Otherwise, other values | ||
| /// in storage can be compromised. |
There was a problem hiding this comment.
why do we remove this warning and information here ?
I think it is useful for user of StorageNMap to know how the storage is actually implemented and to be warns about its usage no ?
|
Hey, is anyone still working on this? Due to the inactivity this issue has been automatically marked as stale. It will be closed if no further activity occurs. Thank you for your contributions. |
|
The CI pipeline was cancelled due to failure one of the required jobs. |
|
The CI pipeline was cancelled due to failure one of the required jobs. |
I started by performing an exercise that I have suggested myself a few weeks ago: start writing a pallet, from scratch, with minimal copy-pasting. I have two goals:
This is related to 1. While coding a pallet, your IDE will give readily allow you to see the docs of two components:
pallet::storagemacro, which is coming from a stub inframe_support_procedural.storage::types, egStorageValue.This PR moves all the relevant documentation of storage items into either of these two, while not repeating anything.
An open issue I have, which is also highlighted as a TODO in the code is:
I want to link to types like
frame_support::storage::StorageValuein theframe_support_proceduralmacro stub rust-docs. Any way to do that? The code expanded byframe_support_proceduralhas access toframe-support, but I am not sure if the macro code itself can.I would like to next suggest doing the same about weights and benchmarking, given its importance and being one of the biggest pain points for many.