Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

missing_docs_in_private_items config suggestion allow_unused #14413

Open
Qix- opened this issue Mar 15, 2025 · 3 comments · May be fixed by #14453
Open

missing_docs_in_private_items config suggestion allow_unused #14413

Qix- opened this issue Mar 15, 2025 · 3 comments · May be fixed by #14453
Assignees
@quangcito
Labels
A-lint Area: New lints good-first-issue These issues are a good way to get started with Clippy

Comments

@Qix-
Copy link

Qix- commented Mar 15, 2025 •
edited by rustbot
Loading

What it does

This is a suggestion for an additional configuration option for missing_docs_in_private_items called allow_unused whereby _underscored fields do not have to have documentation even if missing_docs_in_private_items is enabled.

Advantage

When writing structures that must adhere to a specific format (such as memory mapped I/O structures) there are inevitably fields that are "reserved" by specifications and thus need no documentation. In cases where private docs are preferred but reserved fields need no explanation, having to #[allow/expect] this lint removes the ability to check for otherwise used fields' documentation.

Drawbacks

None that I can think of.

Example

/// The memory mapped register block for the HPET.
#[repr(C, align(8))]
struct HpetRegisters {
	/// General capabilities and ID.
	///
	/// **Read only**
	caps_and_id:  Volatile<HpetCapsAndId>,
	/// Reserved.
	_reserved0:   u64,
	/// General Configuration Register
	///
	/// **Read write**
	gen_cfg:      Volatile<u64>,
	/// Reserved.
	_reserved1:   u64,
	/// General Interrupt Status Register
	///
	/// **Read write**
	gen_status:   Volatile<u64>,
	/// Reserved.
	_reserved2:   u64,
	/// Main counter value register
	///
	/// **Read write**
	main_counter: Volatile<u64>,
	/// Reserved.
	_reserved3:   u64,
	/// Timers.
	///
	/// **Note that not all counters are available.**
	/// The [`Self::caps_and_id`] field must be checked
	/// for the number of timers that are present.
	///
	/// As of the 1.0a specification, timers 3 and above
	/// (index 2 and greater) are **reserved**.
	///
	/// Accessing a timer that isn't indicated as available
	/// is **undefined behavior**.
	timers:       [HpetTimer; 1 << 5],
}

Could be written as:

/// The memory mapped register block for the HPET.
#[repr(C, align(8))]
struct HpetRegisters {
	/// General capabilities and ID.
	///
	/// **Read only**
	caps_and_id:  Volatile<HpetCapsAndId>,
	_reserved0:   u64,
	/// General Configuration Register
	///
	/// **Read write**
	gen_cfg:      Volatile<u64>,
	_reserved1:   u64,
	/// General Interrupt Status Register
	///
	/// **Read write**
	gen_status:   Volatile<u64>,
	_reserved2:   u64,
	/// Main counter value register
	///
	/// **Read write**
	main_counter: Volatile<u64>,
	_reserved3:   u64,
	/// Timers.
	///
	/// **Note that not all counters are available.**
	/// The [`Self::caps_and_id`] field must be checked
	/// for the number of timers that are present.
	///
	/// As of the 1.0a specification, timers 3 and above
	/// (index 2 and greater) are **reserved**.
	///
	/// Accessing a timer that isn't indicated as available
	/// is **undefined behavior**.
	timers:       [HpetTimer; 1 << 5],
}
@Qix- Qix- added the A-lint Area: New lints label Mar 15, 2025
@samueltardieu samueltardieu added the good-first-issue These issues are a good way to get started with Clippy label Mar 18, 2025
@quangcito
Copy link

@rustbot claim

@quangcito quangcito linked a pull request Mar 23, 2025 that will close this issue
Open
@cerdelen
Copy link

cerdelen commented Mar 24, 2025 •
edited
Loading

Hi i hope its okay commenting on your PR, i was also trying to tackle this issue and was comparing my solution to yours and hope i could give some idea/recommendation.

Since we only want to allow private fields to not be documented if found the function "check_field_def" in line 262 a better location to check the conditions as this doesnt have any runtime implications for other checks then. And in there you could also directly use sf.ident.as_str() instead of cx.tcx.opt_item_name(sf.def_id.into())) reducing it to 1 less funciton call and 1 less unwrapping of an Option also reducing runtime complexity.

        if self.allow_unused && sf.ident.as_str().starts_with('_') {
                return;
        }

Apart from that good luck with your PR beating me to it :D

@quangcito
Copy link

hi @cerdelen thank you for the recommendation! After checking, I realized it is indeed better to move it under check_field_def since this exemption should only apply to struct fields with underscores, not all underscored items. Other than the reasons you mentioned about efficiency, I also realized this change better aligns with the original requirements of the issue. I've pushed a change that incorporates your suggestion. Thanks for the helpful feedback!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@quangcito quangcito

Labels
A-lint Area: New lints good-first-issue These issues are a good way to get started with Clippy
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

add allow_unused config to missing_docs_in_private_items quangcito/rust-clippy
4 participants
@samueltardieu @Qix- @quangcito @cerdelen