paritytech / substrate

Substrate: The platform for blockchain innovators
Apache License 2.0
8.39k stars 2.65k forks source link

[fix lint warnings: Uniques pallet] fix clippy::missing_docs_in_private_items warnings #14591

Closed sacha-l closed 1 year ago

sacha-l commented 1 year ago

This PR fixes 6 out of the 8 lint warnings emitted by the missing_docs_in_private_items lint in the Uniques pallet by adding docs to the relevant types. The remaining 2 warnings have to do with the outer macro pattern I believe and may need to be addressed as a separate task (cc @sam0x17):

warning: missing documentation for a module
   --> frame/uniques/src/lib.rs:441:12
    |
441 |     #[pallet::call]
    |               ^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_docs_in_private_items
    = note: requested on the command line with `-W clippy::missing-docs-in-private-items`

warning: missing documentation for an associated function
   --> frame/uniques/src/lib.rs:280:29
    |
280 |     #[pallet::generate_deposit(pub(super) fn deposit_event)]
    |                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_docs_in_private_items

This is part of an ongoing effort from the https://github.com/orgs/paritytech/teams/devrel team to improve developer experience.

aaronbassett commented 1 year ago

Why do we need docs on private things?

Adding docs to public items should be our priority, but we should also try and document the private items because we frequently tell folks to "read the code" when it comes to learning Substrate.

If we were only directing people to the rustdocs then completely agree that we would only need to document those elements which make up the public interface—although having the private items documented certainly wouldn't hurt us—but as we're explicitly directing people to read the code too, then we really should try to ensure that all of the code is documented.

sacha-l commented 1 year ago

bot merge

paritytech-processbot[bot] commented 1 year ago

Error: Statuses failed for 176f6848f2002e026d2bcea69dceb241b24ccd80

sam0x17 commented 1 year ago

Why do we need docs on private things?

tooltips in RA when people are poking around. I actually document all my private items across the board in my crates, for my own sanity.

sacha-l commented 1 year ago

bot merge

paritytech-processbot[bot] commented 1 year ago

Error: Statuses failed for 176f6848f2002e026d2bcea69dceb241b24ccd80

sacha-l commented 1 year ago

@sam0x17 - can you ask the bot nicely to merge ? I don't have authorization 🙈

sam0x17 commented 1 year ago

@sam0x17 - can you ask the bot nicely to merge ? I don't have authorization see_no_evil

looks like cumulus and zombienet are still failing

jsidorenko commented 1 year ago

bot merge

paritytech-processbot[bot] commented 1 year ago

Error: Statuses failed for 176f6848f2002e026d2bcea69dceb241b24ccd80

ggwpez commented 1 year ago

bot rebase

paritytech-processbot[bot] commented 1 year ago

Rebased

ggwpez commented 1 year ago

bot merge

paritytech-processbot[bot] commented 1 year ago

Waiting for commit status.