Mention on which items the missing_doc_code_examples is not emitted

[GuillaumeGomez]

As mentioned in #154048, the lint's documentation didn't mention which items were ignored. This PR fixes that.

r? @lolbinarycat

[lolbinarycat]

We should also mention it isn't checked on private/hidden items (also clarify if that behavior is changed by --document-private-items and/or --document-hidden-items). If we want to avoid the documentation being overly verbose, we could word it very particularly, such as by saying it checks items that will be rendered in the documentation (if the flags affect it), or by saying it checks items that are normally render in the documentation (if the flags have no effect). Potentially we could also provide clarification in a footnote.

Additionally, we should clarify what counts as a "code example". Does it have to be a doctest (i.e. does ignore not count)? Any rust code block? Any code block? Once we decide on a behavior we want, we'll also need tests for that behavior.

I was looking through the tests to make sure they reflect what is documented here, and it looks like we'll need yet another followup (or several) because there's quite a few missing cases.

From those mentioned here (checked=tests exist):

• Impl blocks
• Enum variants
• Struct/union fields
• (associated) Type aliases
• Statics/constants
• Modules
• Inlined reexports (cross-crate)
• Inlined reexports (intra-crate)
• Non-inlined reexports (cross-crate)
• Non-inlined reexports (intra-crate)
• Inherient associated constants
• Trait associated constants
• Required trait associated types
• Optional trait associated types

Additional tests needed:

• All 3 kinds of macros (v2, macro_rules, proc_macro). Currently these (at least macro_rules macros) are not linted on, but I feel like they should be.
• Trait definitions
• Trait items in a trait definition (all of them, including both required and non-required methods)
• pub extern crate items.
• Everything that can appear in an extern block (functions, statics, and types)

I based this off the variants of rustdoc::clean::types::ItemKind, so it should be comprehensive, but there's still a chance I overlooked something.

This is a lot, so it might be worth it to open a tracking issue with E-help-wanted and/or E-mentor, but for a lot of these cases, it is an open question what rustdoc should do, which makes it less ideal for new contributors than it may initially seem.

View changes since this review

[lolbinarycat]

Suggested change

	* Impl blocks
	* Enum variants
	* Struct/union fields
	* (associated) Type aliases
	* Statics/constants
	* Modules
	* Foreign items (functions, statics, types, etc)
	* Impl blocks (both trait and inherent)
	* Enum variants
	* Struct/union fields
	* Type aliases, including associated types
	* Statics/constants
	* Modules (including the top-level module of a crate)
	* Foreign items (functions, statics, types, etc)

I think this improves clarity a bit.

Additionally, by "Foreign items", do you mean inlined cross-crate reexports, or items from an extern block? The term is used a bit inconsistently within rustdoc.

Rationale for rewording

My biggest concerns are making it clear that top-level docs are module docs, and the use of parenthesis that, while standard, may not be immediately intuitive to all readers.

[GuillaumeGomez]

Makes sense, applying the suggestion.

[GuillaumeGomez]

I also opened #154640 to keep track of it.

[GuillaumeGomez]

Updated too.

[lolbinarycat]

You still haven't clarified what you mean by "foreign items" (reexports? or extern items?)

[GuillaumeGomez]

Ah I meant reexports. Gonna update.

[lolbinarycat]

I would prefer we avoided the word "foreign" altogether due to its ambiguity, but we use it other places in the rustdoc book, so it's fine for now. I'll probably go through and replace all instances of it in the future when I've got the time.

@bors r+

[rust-bors]

📌 Commit f8a8b8f has been approved by lolbinarycat

It is now in the queue for this repository.