Metadata V15: Expose pallet documentation (#13452)

* frame/proc: Helpers to parse pallet documentation attributes

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* frame/proc: Expand pallet with runtime metadata documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* frame/dispatch: Implement doc function getter for dispatch

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* frame/tests: Check exposed runtime metadata documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* frame/tests: Add UI tests for `pallet_doc` attribute

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* frame/proc: Document pallet_doc attribute

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* frame/support: Use `derive_syn_parse`

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* Update frame/support/procedural/src/lib.rs

Co-authored-by: Niklas Adolfsson <niklasadolfsson1@gmail.com>

* frame/support: Improve documentation

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

---------

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>
Co-authored-by: parity-processbot <>
Co-authored-by: Niklas Adolfsson <niklasadolfsson1@gmail.com>

substrate/frame/support/test/tests/pallet.rs

@@ -101,6 +101,10 @@ impl SomeAssociation2 for u64 {
 }
 
 #[frame_support::pallet]
+/// Pallet documentation
+// Comments should not be included in the pallet documentation
+#[pallet_doc("../../README.md")]
+#[doc = include_str!("../../README.md")]
 pub mod pallet {
 	use super::*;
 	use frame_support::pallet_prelude::*;
@@ -1589,6 +1593,14 @@ fn metadata() {
 	pretty_assertions::assert_eq!(actual_metadata.pallets, expected_metadata.pallets);
 }
 
+#[test]
+fn test_pallet_runtime_docs() {
+	let docs = crate::pallet::Pallet::<Runtime>::pallet_documentation_metadata();
+	let readme = "Support code for the runtime.\n\nLicense: Apache-2.0";
+	let expected = vec![" Pallet documentation", readme, readme];
+	assert_eq!(docs, expected);
+}
+
 #[test]
 fn test_pallet_info_access() {
 	assert_eq!(<System as frame_support::traits::PalletInfoAccess>::name(), "System");

substrate/frame/support/test/tests/pallet_ui/pallet_doc_arg_non_path.rs

@@ -0,0 +1,16 @@
+#[frame_support::pallet]
+// Must receive a string literal pointing to a path
+#[pallet_doc(X)]
+mod pallet {
+	#[pallet::config]
+	pub trait Config: frame_system::Config
+	where
+		<Self as frame_system::Config>::Index: From<u128>,
+	{
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(core::marker::PhantomData<T>);
+}
+
+fn main() {}

substrate/frame/support/test/tests/pallet_ui/pallet_doc_arg_non_path.stderr

@@ -0,0 +1,5 @@
+error: The `pallet_doc` received an unsupported argument. Supported format: `pallet_doc(PATH)`
+ --> tests/pallet_ui/pallet_doc_arg_non_path.rs:3:1
+  |
+3 | #[pallet_doc(X)]
+  | ^

substrate/frame/support/test/tests/pallet_ui/pallet_doc_empty.rs

@@ -0,0 +1,16 @@
+#[frame_support::pallet]
+// Expected one argument for the doc path.
+#[pallet_doc]
+mod pallet {
+	#[pallet::config]
+	pub trait Config: frame_system::Config
+	where
+		<Self as frame_system::Config>::Index: From<u128>,
+	{
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(core::marker::PhantomData<T>);
+}
+
+fn main() {}

substrate/frame/support/test/tests/pallet_ui/pallet_doc_empty.stderr

@@ -0,0 +1,5 @@
+error: The `pallet_doc` attribute must receive arguments as a list. Supported format: `pallet_doc(PATH)`
+ --> tests/pallet_ui/pallet_doc_empty.rs:3:1
+  |
+3 | #[pallet_doc]
+  | ^

substrate/frame/support/test/tests/pallet_ui/pallet_doc_invalid_arg.rs

@@ -0,0 +1,16 @@
+#[frame_support::pallet]
+// Argument expected as list, not named value.
+#[pallet_doc = "invalid"]
+mod pallet {
+	#[pallet::config]
+	pub trait Config: frame_system::Config
+	where
+		<Self as frame_system::Config>::Index: From<u128>,
+	{
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(core::marker::PhantomData<T>);
+}
+
+fn main() {}

substrate/frame/support/test/tests/pallet_ui/pallet_doc_invalid_arg.stderr

@@ -0,0 +1,5 @@
+error: The `pallet_doc` attribute must receive arguments as a list. Supported format: `pallet_doc(PATH)`
+ --> tests/pallet_ui/pallet_doc_invalid_arg.rs:3:1
+  |
+3 | #[pallet_doc = "invalid"]
+  | ^

substrate/frame/support/test/tests/pallet_ui/pallet_doc_multiple_args.rs

@@ -0,0 +1,16 @@
+#[frame_support::pallet]
+// Supports only one argument.
+#[pallet_doc("A", "B")]
+mod pallet {
+	#[pallet::config]
+	pub trait Config: frame_system::Config
+	where
+		<Self as frame_system::Config>::Index: From<u128>,
+	{
+	}
+
+	#[pallet::pallet]
+	pub struct Pallet<T>(core::marker::PhantomData<T>);
+}
+
+fn main() {}

substrate/frame/support/test/tests/pallet_ui/pallet_doc_multiple_args.stderr

@@ -0,0 +1,5 @@
+error: The `pallet_doc` attribute must receive only one argument. Supported format: `pallet_doc(PATH)`
+ --> tests/pallet_ui/pallet_doc_multiple_args.rs:3:1
+  |
+3 | #[pallet_doc("A", "B")]
+  | ^