Improve FRAME storage docs

[wentelteefje]

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-Analyzer users**: See the documentation of the Rust item in
/// `frame_support::pallet_macros::storage`.

we could write

/// **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:

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
• 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

[kianenigma]

another idea is for you to add a single test/snippet here to each storage type where you re-create the storage key to demonstrate the point. Something like:

fn main() {
	let expected_key = twox(pallet_name) ++ twox(Foo)
	let key = Foo::hashed_key();
	assert_eq!(expected., key);
}

Sadly would require you to build a runtime, but thanks to all the recent work it is only a few lines of code now :)

[kianenigma]

newlines can probably go away for readability?

[kianenigma]

we can faily easily add something like this:

fn main() {
	let call = pallet::Call::do_stuff { .. }
	let origin = ..
	call.dispatch(origin);
}

[kianenigma]

I think these don't fit great into the story so far. Moving them toward the end might improve, but no sure. Do you think they are well explained in this position, in the overall narrative?

[kianenigma]

This is one that I would probably tackle in a ref-doc, as it is too detailed. Good for now I would say.

[kianenigma]

ahh, so maybe you don't need to cover the key generation details of each storage type in each type, and tackle them all here?

[wentelteefje]

I have given an example for StorageValue and StorageMap. However, I'm still thinking about whether I should add them additionally for each type in their respective pages...

[kianenigma]

Looks mostly good, but I have some improvement suggestions.

Next, I suggest you to tackle pallet::Config. It is probably the last "important" one to tackle among the foundations of pallets.

I think that would also be a good alignment exercise for us, so I can see how you would tackle one from scratch and give you feedback. Because I had written the foundations of this myself, it was hard for me to measure.

[paritytech-cicd-pr]

The CI pipeline was cancelled due to failure one of the required jobs.
Job name: cargo-clippy
Logs: https://gitlab.parity.io/parity/mirrors/polkadot-sdk/-/jobs/3991823

[sam0x17]

great use of docify!

[kianenigma]

LGTM, it is not perfect but HUGE step in the right direction, rather merge soon and iterate later.

It is part of paritytech/polkadot-sdk-docs#31

[CrackTheCode016]

This looks really good for a first iteration. We can still of course provide a bit more clarity on the dependnecies that storage types may use, and how they relate, etc (as well as improve things like the kitchensink bit), but this is a huge improvement!

[wentelteefje]

LGTM, it is not perfect but HUGE step in the right direction, rather merge soon and iterate later.

Yes, please go ahead. I still have quite a few ideas, but for these I'll open separate PRs later on. Curious to see how this develops :)

[kianenigma]

@wentelteefje feel free to sign up to continuing with this or other macros in paritytech/polkadot-sdk-docs#31