This repository has been archived by the owner on Nov 15, 2023. It is now read-only.
macro stubs for all pallet:: macros to improve documentation visibility and discovery + revamp of pallet macro documentation #12334
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
the
A3-in_progress
sam0x17
added
Z1-easy
bkchr
reviewed
Sep 23, 2022
|
Note that I've been going a step further with this -- it turns out the docs on that page had a lot of grammatical errors and formatting confusions so I've been fixing up the whole thing and adding a more navigable and complete table of all the pallet macros :) |
* fix docs for pallet::getter * fix docs for pallet::storage_prefix * fix docs for pallet::unbounded * fix docs for pallet::whitelist_storage * fix docs for #[cfg(..)] (for storage items and attributes) * fix docs for pallet::storage macro expansion
KiChjang
reviewed
Oct 5, 2022
|
bot rebase |
|
Rebased |
|
bot rebase |
|
Rebased |
|
bot rebase |
|
Branch is already up-to-date |
|
bot merge |
|
This pull request has been mentioned on Polkadot Forum. There might be relevant details there: https://forum.polkadot.network/t/polkadot-release-analysis/1026/2 |
ark0f
pushed a commit
to gear-tech/substrate
that referenced
this pull request
Feb 27, 2023
…ty and discovery + revamp of pallet macro documentation (paritytech#12334) * proof of concept working for pallet::whitelist_storage * fix comments * pallet macros docs rewrite WIP * fix issue with cargo fmt cobbling links * tweak capitalization * fix docs for storage_version * fix docs for pallet::hooks * fix several comments * fix invalid link * fix wrapping and add missing links for pallet::hooks docs * run rewrap on all text blocks in frame_support::pallet docs * cargo fmt * fix up pallet::call_index docs * fix docs for pallet::extra_constants * fix docs for pallet::error * fix docs for pallet::event * fix docs for pallet::event * * fix docs for pallet::storage * fix docs for pallet::getter * fix docs for pallet::storage_prefix * fix docs for pallet::unbounded * fix docs for pallet::whitelist_storage * fix docs for #[cfg(..)] (for storage items and attributes) * fix docs for pallet::storage macro expansion * fix docs for pallet::type_value * fix docs for pallet::genesis_config * fix docs for pallet::genesis_build * fix docs for pallet::inherent * fix docs for pallet::validate_unsigned * fix docs for pallet::origin * fix docs for general notes on instantiable pallets * fix docs for example of a non-instantiable pallet * fix docs for example of an instantiable pallet * fix docs for upgrade guidelines * fix docs for upgrade guidelines * fix docs for upgrade checking and final notes * fix some examples near the beginning * extract docs for `pallet::whitelist_storage` * add docs for pallet_macro_stub * fix order of pallet::config and pallet::constant * set up stub for pallet::config * set up stub for pallet::constant * fix * set up stub for pallet::disable_frame_system_supertrait_check * set up stub for pallet::generate_storage_info * set up stub for pallet::storage_version * set up stub for pallet::hooks * set up stub for pallet::weight * set up stub for pallet::compact * set up stub for pallet::call_index * set up stub for pallet::extra_constants * set up stub for pallet::error * set up stub for pallet::event * set up stub for pallet::generate_deposit * set up stub for pallet::storage * set up stub for pallet::getter * set up stub for pallet::storage_prefix * set up stub for pallet::unbounded * set up stub for pallet::type_value * set up stub for pallet::genesis_config * set up stub for pallet::genesis_build * set up stub for pallet::inherent * set up stub for pallet::validate_unsigned * set up stub for pallet::origin * fix comment * cargo fmt * tweak error message * Update frame/support/procedural/src/lib.rs Co-authored-by: Keith Yeung <kungfukeith11@gmail.com> * Update frame/support/procedural/src/lib.rs Co-authored-by: Keith Yeung <kungfukeith11@gmail.com> * switch order of derives Co-authored-by: Squirrel <gilescope@gmail.com> * tweak wording Co-authored-by: Squirrel <gilescope@gmail.com> * add more context info about `MAX_MODULE_ERROR_ENCODED_SIZE` Co-authored-by: Squirrel <gilescope@gmail.com> * tweak wording about where clause Co-authored-by: Squirrel <gilescope@gmail.com> * clarify wording about system/events key Co-authored-by: Squirrel <gilescope@gmail.com> * use "The Event enum" instead of "item" Co-authored-by: Squirrel <gilescope@gmail.com> * fix bad wording Co-authored-by: Squirrel <gilescope@gmail.com> * use enum instead of type Co-authored-by: Squirrel <gilescope@gmail.com> * expect => expects Co-authored-by: Squirrel <gilescope@gmail.com> * add additional note about storage prefix Co-authored-by: Squirrel <gilescope@gmail.com> * clearer note about GenesisConfig Co-authored-by: Squirrel <gilescope@gmail.com> * Use "The impl" instead of "The item" Co-authored-by: Squirrel <gilescope@gmail.com> * add note and link to tight-coupling docs Co-authored-by: Squirrel <gilescope@gmail.com> * cargo fmt * remove spaces around parenthesis * fix missing text for pallet::config * fix issue with pallet::constant intro * fix wording about codec index * fix pallet::error wording * fix comment about 1 byte => 256 errors * fix where clause comment * fix comment about where pallet events are stored * rewrap some text * fix pallet::storage docs * fix pallet::storage_prefix docs * tweak docs for pallet::genesis_build * tweak docs for pallet::config * specify that pallet::event must be present if pallet::config is present * add note about why we would want to bypass the supertrait check * mention that pallet::generate_store attribute is only valid on pallet struct * add note about adding new calls to the end to maintain existing order * add note about pallet::type_value and pallet::storage Co-authored-by: Squirrel <gilescope@gmail.com> * add note about using pallet::type_value alongside pallet::storage * include warning about modifying disaptchables on other pallet::call_index docs page * fix incorrect comment * add much more information for pallet::inherent * move pallet::pallet macro expansion notes back to their rightful place * re-run CI * fix macro expansion appearing in wrong place for pallet::pallet * replicate pallet::pallet docs on the pallet::pallet macro stub * force CI re-run Co-authored-by: Keith Yeung <kungfukeith11@gmail.com> Co-authored-by: Squirrel <gilescope@gmail.com> Co-authored-by: parity-processbot <>
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
This PR adds macro stubs in
frame_support_proceduralfor all of thepallet::macros, moves documentation for the specificpallet::macros to their respective macro stubs (note that we do keep the majority of it where it was, only things like expansion info are truly moved), and finally includes the stubs as part of the pallet prelude. Additionally this PR substantially upgrades and re-writes a lot of the pallet macro documentation. This results in several key developer experience improvements:pallet::macros when they hover over them (right now they see nothing)pallet::macro and select "Go to Definition" successfully (right now it fails to find the definition)For context, the reason we don't already have stubs for these macros is we use them essentially as markers that later have their AST nodes removed by the pallet expansion macro. In other words definitions for these macros don't actually need to exist in our codebase for them to function properly, since all the code associated with these markers is elsewhere in the pallet expansion macro machinery.
Note I ended up also substantially re-writing/fixing up the existing pallet macro documentation, as noted in my line comments.
Related Issues
Proof of Concept