doc-only module to group all storage items of a pallet

[kianenigma]

A simple one: create a

#[cfg(doc)]
pub mod storage_types {
   pub use crate::pallet::every_public_storage_item;
}

for nicer discoverability in rustdocs.

Essentially, similar to this page, but better:

https://polkadot.js.org/docs/substrate/storage/#staking

[kianenigma]

cc @sam0x17

[sam0x17]

This would be a good add-on or follow-up to #12334

[bkchr]

We should not only list all the public storage types. We should probably support having all of them shown in the docs, not just the public ones.

[kianenigma]

We should probably support having all of them shown in the docs, not just the public ones.

Yeah, let's do that. Might be a little confusing though because some of them might not be public in the Rust code.

This pub mod storage_types {} should have a clear documentation saying that what's named here might not be publicly available in the API and is only listed as reference.

[kianenigma]

This would be a good add-on or follow-up to #12334

I think they are rather unrelated in terms of what needs to be done for it, but yeah perhaps a follow-up for you once you are finished there, feel free to assign to yourself :)

[kianenigma]

@olliecorbisiero this is the fix for what we spoke of today.

[kianenigma]

This is currently blocked by the fact that some storage types can be made pub(crate).

Option 1: All storage items must be public and visible in the rust-docs.
Option 2: All storage items are artificially #[cfg(doc)] pub #[cfg(not(doc))] $vis. A bit confusing eh?
Option 3: non-public storage items will not go into rust-docs.

I would go with either option 1 or 3 for now.

[bkchr]

Option 4: cargo doc --document-private-items

Option 3: non-public storage items will not go into rust-docs.

Sounds reasonable, as you only see the storage items that you can access.

Option 1: All storage items must be public and visible in the rust-docs.

We could add some warning when you use something that isn't pub :D A lot of people always complain that storage items aren't public, which doesn't make that much sense as when you know they key you can just modify all of them.

[kianenigma]

@ggwpez @KiChjang @shawntabrizi if you are more or less on the same page, let's consider option 1.

[KiChjang]

Well, in that case, why don't we just remove the ability to set visibility on storages? Sounds like we can just modify the macro to do so.

[bkchr]

We could, but a warning is probably better from the usability.

[sam0x17]

Bear in mind custom warnings aren't stabilized in rust yet (unless this happened very recently without me knowing) so this is often harder than it sounds

[bkchr]

Yeah I know, but yeah, we could also make it a compile_error. However, we should ensure that we generate the correct code plus the compile error. Otherwise people would get tons of unrelated compile errors.

[kianenigma]

@sam0x17 if you want to pickup #13341 and related tasks, please feel free to do so.

[sam0x17]

@kianenigma Yeah I'll pick that up. It's well timed because I'm wrapping up #13224 today