[fix docs compiler warnings] Examples pallets #14669

sacha-l · 2023-07-28T09:20:33Z

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

gupnik

Thank you!

sacha-l · 2023-07-31T15:56:36Z

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 · 2023-07-31T20:03:38Z

@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 · 2023-07-31T20:44:14Z

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 · 2023-07-31T22:12:56Z

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 · 2023-08-01T05:13:47Z

@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.

sam0x17

awesome good find. I didn't realize the problem was specifically with the dev mode pallet example -- I went digging in dev mode expansion to find stuff that might be missing docs in the expansion (for all dev mode pallets) but lol

Thanks!!!!

sacha-l · 2023-08-01T17:22:59Z

@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.

kianenigma · 2023-08-03T16:55:58Z

frame/examples/kitchensink/src/lib.rs

@@ -301,11 +315,14 @@ pub mod pallet {
 	#[pallet::validate_unsigned]
 	impl<T: Config> ValidateUnsigned for Pallet<T> {
 		type Call = Call<T>;
-		fn validate_unsigned(_: TransactionSource, _: &Self::Call) -> TransactionValidity {
+
+		/// Validates an unsigned transaction.


Trait functions should not be documented, the trait definition itself should be.

kianenigma · 2023-08-03T16:56:37Z

frame/examples/offchain-worker/src/lib.rs

@@ -242,19 +244,18 @@ pub mod pallet {
 		/// Submit new price to the list via unsigned transaction.
 		///
 		/// Works exactly like the `submit_price` function, but since we allow sending the
-		/// transaction without a signature, and hence without paying any fees,
-		/// we need a way to make sure that only some transactions are accepted.
-		/// This function can be called only once every `T::UnsignedInterval` blocks.


If you find a linter that will prohibit people from immaturely wrapping their lines early, I will indefinitely be grateful of you.

If you find a linter that will prohibit people from immaturely wrapping their lines early, I will indefinitely be grateful of you.

💯

sacha-l · 2023-08-15T08:00:16Z

bot rebase

…-example-pallet

paritytech-processbot · 2023-08-15T08:00:23Z

Rebased

sacha-l · 2023-08-18T12:45:18Z

bot rebase

…-example-pallet

paritytech-processbot · 2023-08-18T12:45:24Z

Rebased

paritytech-cicd-pr · 2023-08-18T12:50:04Z

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

Sacha Lansky added 3 commits July 28, 2023 05:56

fix missing docs dev-mode

5a7b305

fix missing docs warnings

479d65c

fix missing docs warnings ocw

29b42e7

sacha-l requested review from sam0x17, kianenigma, gupnik and a team July 28, 2023 09:20

gupnik approved these changes Jul 29, 2023

View reviewed changes

add #![deny(missing_docs)]

0e21310

sacha-l requested a review from ggwpez July 31, 2023 15:35

Adds doc for pallet calls in pallet-dev-mode

0708a75

sam0x17 approved these changes Aug 1, 2023

View reviewed changes

Sacha Lansky added 2 commits August 1, 2023 10:24

add missing docs to ocw example

910b9e1

fmt

406965b

Sacha Lansky added 4 commits August 1, 2023 15:28

fix docs in pallet-example-basic

3a840a9

fix missing docs for pallet-example-kitchensink

344a8ab

fmt

2303d9b

add docs for pallet-example-kitchensink

a5ce92f

fmt

b72b693

kianenigma reviewed Aug 3, 2023

View reviewed changes

KiChjang approved these changes Aug 5, 2023

View reviewed changes

Merge remote-tracking branch 'origin/master' into sl/fix-doc-warnings…

ac4d907

…-example-pallet

bkchr approved these changes Aug 16, 2023

View reviewed changes

Merge remote-tracking branch 'origin/master' into sl/fix-doc-warnings…

ad6a71a

…-example-pallet

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[fix docs compiler warnings] Examples pallets #14669

[fix docs compiler warnings] Examples pallets #14669

sacha-l commented Jul 28, 2023

gupnik left a comment

sacha-l commented Jul 31, 2023

sam0x17 commented Jul 31, 2023

sam0x17 commented Jul 31, 2023

sacha-l commented Jul 31, 2023

gupnik commented Aug 1, 2023

sam0x17 left a comment •

edited

Loading

sacha-l commented Aug 1, 2023

kianenigma Aug 3, 2023

kianenigma Aug 3, 2023

sam0x17 Aug 4, 2023

sacha-l commented Aug 15, 2023

paritytech-processbot bot commented Aug 15, 2023

sacha-l commented Aug 18, 2023

paritytech-processbot bot commented Aug 18, 2023

paritytech-cicd-pr commented Aug 18, 2023

[fix docs compiler warnings] Examples pallets #14669

Are you sure you want to change the base?

[fix docs compiler warnings] Examples pallets #14669

Conversation

sacha-l commented Jul 28, 2023

gupnik left a comment

Choose a reason for hiding this comment

sacha-l commented Jul 31, 2023

sam0x17 commented Jul 31, 2023

sam0x17 commented Jul 31, 2023

sacha-l commented Jul 31, 2023

gupnik commented Aug 1, 2023

sam0x17 left a comment • edited Loading

Choose a reason for hiding this comment

sacha-l commented Aug 1, 2023

kianenigma Aug 3, 2023

Choose a reason for hiding this comment

kianenigma Aug 3, 2023

Choose a reason for hiding this comment

sam0x17 Aug 4, 2023

Choose a reason for hiding this comment

sacha-l commented Aug 15, 2023

paritytech-processbot bot commented Aug 15, 2023

sacha-l commented Aug 18, 2023

paritytech-processbot bot commented Aug 18, 2023

paritytech-cicd-pr commented Aug 18, 2023

sam0x17 left a comment •

edited

Loading