[fix docs compiler warnings] Examples pallets

[sacha-l]

This PR fixes the following 38 compiler warnings when running RUSTFLAGS="-W missing_docs" cargo check -p pallet-examples :

• pallet-example-offchain-worker (lib) generated 4 warnings
• pallet-example-kitchensink (lib) generated 11 warnings
• pallet-example-basic (lib) generated 13 warnings
• pallet-dev-mode (lib) generated 6 warnings
• pallet-example-split (lib) generated 4 warnings

[sacha-l]

CI fails now because:

error: could not compile `pallet-example-offchain-worker` (lib) due to previous error
warning: build failed, waiting for other jobs to finish...
error: missing documentation for an associated function
  --> frame/examples/dev-mode/src/lib.rs:45:1
   |
45 | #[frame_support::pallet(dev_mode)]
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
note: the lint level is defined here
  --> frame/examples/dev-mode/src/lib.rs:28:9
   |
28 | #![deny(missing_docs)]
   |         ^^^^^^^^^^^^
   = note: this error originates in the attribute macro `frame_support::pallet` (in Nightly builds, run with -Z macro-backtrace for more info)

error: could not compile `pallet-dev-mode` (lib) due to previous error
error: missing documentation for an associated function
  --> frame/examples/kitchensink/src/lib.rs:46:1
   |
46 | #[frame_support::pallet]
   | ^^^^^^^^^^^^^^^^^^^^^^^^
   |
note: the lint level is defined here
  --> frame/examples/kitchensink/src/lib.rs:28:9
   |
28 | #![deny(missing_docs)]
   |         ^^^^^^^^^^^^
   = note: this error originates in the attribute macro `frame_support::pallet` (in Nightly builds, run with -Z macro-backtrace for more info)

error: missing documentation for an associated function
   --> frame/examples/kitchensink/src/lib.rs:235:29
    |
235 |     #[pallet::generate_deposit(pub fn deposit_event)]
    |   

@sam0x17 any advice on how we may be able to fix this?

[sam0x17]

@sam0x17 any advice on how we may be able to fix this?

This is likely some item in the expansion of dev_mode that does not come with built-in doc comments. I will poke around and see what I can find but feel free to jump in @gupnik

[sam0x17]

So glancing through the dev mode implementation I didn't catch any undocumented items slipping through. Could you open the docs on the item it is complaining about @sacha-l and see if there is an undocumented associated function in the rust docs for that item and if so what it is?

[sacha-l]

I think this is related to the same reasons the I wasn't able to fix the warnings mentioned here.

Could you open the docs on the item it is complaining about @sacha-l and see if there is an undocumented associated function in the rust docs for that item and if so what it is?

After running RUSTFLAGS="-W missing_docs" cargo check -p frame-system I can see there are 22 warnings emitted. Do you think addressing those will fix this?

What I don't understand is with Rust analyzer running I'm able to verify that the docs for deposit_event are coming through. But the compiler is still complaining about them not existing.

Same for the pallet macro:

When I hover over the dev_mode item though, no docs show up at all.

[gupnik]

@sacha-l @sam0x17 I think the docs for calls were missing. I have added some in pallet-dev-mode and the check seems to succeed. We will probably need to add the same for other crates as well.

[sacha-l]

@sacha-l @sam0x17 I think the docs for calls were missing. I have added some in pallet-dev-mode and the check seems to succeed. We will probably need to add the same for other crates as well.

Thanks ! Applying these fixes to the other pallet lib.rs files.

[sacha-l]

bot rebase

[paritytech-processbot[bot]]

Rebased

[sacha-l]

bot rebase

[paritytech-processbot[bot]]

Rebased

[paritytech-cicd-pr]

The CI pipeline was cancelled due to failure one of the required jobs. Job name: cargo-check-benches Logs: https://gitlab.parity.io/parity/mirrors/substrate/-/jobs/3412671