Followup test for checking propagated documentation

[lexnv]

This PR adds a test that compares the raw documentation, from a
RuntimeMetadataV14 object, with the documentation propagated
to the RuntimeApi.

The documentation is extracted from each Type of the RuntimeMetadataV14, which
is obtained via the test-runtime crate. A new RuntimeApi is generated locally
to not rely on hardcoded paths to the codegen/polkadot.rs interface, nor make
any assumptions about the underlying node, may it be Substrate or Polkadot.

The test provided valuable insights into the missing documentation that should have
been propagated to the RuntimeApi.

Changes to the API

#[doc = "\n\t\t\tThe [event](https://docs.substrate.io/v3/runtime/events-and-errors) emitted\n\t\t\tby this pallet.\n\t\t\t"]
^^^^^ was missing

pub enum Event {


#[doc = "\n\t\t\tCustom [dispatch errors](https://docs.substrate.io/v3/runtime/events-and-errors)\n\t\t\tof this pallet.\n\t\t\t"]
^^^^^ was missing

pub enum Error {
   #[codec(index = 0)]
   #[doc = "Inclusion inherent called more than once per block."]


#[doc = "Contains one variant per dispatchable that can be called by an extrinsic."]
^^^^^ was missing

pub enum Call {
   #[codec(index = 0)]
   #[doc = "Service a single overweight upward message."]

[jsdw]

I wonder whether we should look at the lines here and strip any common spacing (eg in this case, every line begins with 3 tabs, so perhaps we should remove 3 tabs from each line?

Also, separately, perhaps it makes sense to remove any leading and trailing newlines?

I'm not too bothered if this doesn't happen though, since the documentation isn't visible in the "common" macro usage, and only really becomes useful if a user generates the code manually.

[jsdw]

Does this mean that all generated docs end up on one line? Should we split it over multiple lines. I wonder how the docs actually look when opened in cargo doc --open for instance?

[lexnv]

The \n and \t cases originate from the substrate generation of the documentation

event_item.attrs.push(syn::parse_quote!(
			#[doc = r"
			The [event](https://docs.substrate.io/v3/runtime/events-and-errors) emitted
			by this pallet.
			"]
		));

leading to a single line

#[doc = "\n\t\t\tThe [event](https://docs.substrate.io/v3/runtime/events-and-errors) emitted\n\t\t\tby this pallet.\n\t\t\t"]

However, those lines are rendered correctly by the cargo doc --open.

[jsdw]

Perfect, thank you :) we can tidy up the extraneous space characters in a future PR then!

[jsdw]

I guess if any doc string contains "] we'd hit an issue here?

perhaps it could also be:

let re = Regex::new(r#"\# \[doc = "[^\n]*"\]"#).unwrap();

To just explicitly forbid actual newlines from appearing and force the match to be on one line, for a bit of added reliability?

[lexnv]

Had a try printing all the documentation pulled from the generated file
Seems to be also handling the cases for extra ]:

			The [event](https://docs.substrate.io/v3/runtime/events-and-errors) emitted
			by this pallet.
# <weight>
- `O(1)`.

Although not entirely accurate: https://regex101.com/r/TtWQqO/1 . Seems to handle multiple ] on the same documentation line.
The ^\n didn't seem to match tho 🤔

[jsdw]

LGTM, though note that in #567 I move integration tests into a sub-folder, so if that merges first this will need moving (if it doesn't autoamtically do so :))

[TarikGul]

Super cool 👍

[TarikGul]

lgtm