`missing_docs_in_private_items` config suggestion `allow_unused`

[Qix-]

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],
}

[quangcito]

@rustbot claim

[cerdelen]

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]

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!