Skip to content
This repository was archived by the owner on Nov 15, 2023. It is now read-only.

frame/support: Link call documentation only in prod-modes #14283

Merged
paritytech-processbot merged 1 commit into from
Jun 1, 2023
Merged

frame/support: Link call documentation only in prod-modes #14283

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 18 additions & 6 deletions frame/support/procedural/src/pallet/expand/call.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,10 @@
// limitations under the License.

use crate::{
pallet::{parse::call::CallWeightDef, Def},
pallet::{
parse::call::{CallVariantDef, CallWeightDef},
Def,
},
COUNTER,
};
use proc_macro2::TokenStream as TokenStream2;
Expand Down Expand Up @@ -113,13 +116,22 @@ pub fn expand_call(def: &mut Def) -> proc_macro2::TokenStream {
}
debug_assert_eq!(fn_weight.len(), methods.len());

let fn_doc = methods
.iter()
.map(|method| {
let map_fn_docs = if !def.dev_mode {
// Emit the [`Pallet::method`] documentation only for non-dev modes.
|method: &CallVariantDef| {
let reference = format!("See [`Pallet::{}`].", method.name);
quote!(#reference)
})
.collect::<Vec<_>>();
}
} else {
// For the dev-mode do not provide a documenation link as it will break the
// `cargo doc` if the pallet is private inside a test.
Copy link
Member

@ggwpez ggwpez Jun 1, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is it trying to document a test? I think anything testing should not need to be documented anyway.
The cargo doc should not even look at this, is what i mean.

Copy link
Contributor Author

@lexnv lexnv Jun 1, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe after that substrate PR, we no longer propagate method.docs and we do instead provide a link to [Pallet:: method]. This link will cause the cargo doc step on the cumulus on test/runtime/src/test_pallet.rs, even tho it is declared as:

#[frame_support::pallet(dev_mode)]
pub mod pallet {
#[pallet::call]
	impl<T: Config> Pallet<T> {
		/// A test dispatchable for setting a custom head data in `validate_block`.
		#[pallet::weight(0)]
		pub fn set_custom_validation_head_data(
		...

|method: &CallVariantDef| {
let reference = format!("See `Pallet::{}`.", method.name);
quote!(#reference)
}
};

let fn_doc = methods.iter().map(map_fn_docs).collect::<Vec<_>>();

let args_name = methods
.iter()
Expand Down