Module doc examples

[GuillaumeGomez]

I was going through the libcore and adding missing code examples when I realized the lint was mostly complaining about modules. In my opinion, forcing modules to have code examples doesn't make sense.

What do you think @rust-lang/rustdoc ?

[rust-highfive]

r? @jyn514

(rust_highfive has picked a reviewer for you, use r? to override)

[jyn514]

Can you give an example of the modules that were missing documentation? In general I think it's good to have; for instance https://docs.rs/cranelift-frontend/0.66.0/cranelift_frontend/#example is extremely helpful in seeing how to use the API. Module-level examples are good for showing how to put different parts of the API together, not just what individual functions do (which sometimes isn't very helpful on its own, e.g. https://docs.rs/cranelift-frontend/0.66.0/cranelift_frontend/struct.FunctionBuilder.html#method.inst_results).

I did spot that https://doc.rust-lang.org/stable/std/default/index.html is missing an example, but that's because all the docs are on the trait itself, not the module. So maybe it makes sense to move that to the module instead?

[Manishearth]

Modules often have code examples in my experience. I think we should lint about them. It's okay to duplicate code examples between a module and its contents

[GuillaumeGomez]

But in the case of a crate providing utilities and tools, it seems a bit weird. For example, libstd and libcore provide only tools. What should we put as example at the crate top level doc comment for example?

[jyn514]

If it doesn't make sense, then it should use allow(missing_doc_code_examples). But I don't think that means rustdoc shouldn't ever lint for modules.

[GuillaumeGomez]

That would make a lot of allow(missing_doc_code_examples) in both libstd and libcore. ;)

[Manishearth]

@GuillaumeGomez What we might want is an attribute that allows you to skip linting for just a module but not its contents.

[GuillaumeGomez]

That'd still make a lot of module in both libcore and libstd. I really think that in some cases, modules don't need code examples.

[jyn514]

I don't think rustdoc is the right place to fix this. If libstd doesn't need module examples, then it shouldn't enable the lint - it's off by default anyway. There are a lot of modules that do need linting and those shouldn't be ignored because it's not a good fit for libstd.

[GuillaumeGomez]

I just used libstd as an example. But I'm pretty sure that it's more common to have a module that shouldn't be commented than the opposite.

[Manishearth]

But I'm pretty sure that it's more common to have a module that shouldn't be commented than the opposite.

I disagree: Most modules I've worked on have a reasonable code example that could be used in their documentation. At worst, it's just a copy of a code example from a substruct.

I'm okay with adding a doc attribute that lets you skip this lint for a module, given that there is no way to apply allow() to a module and not have it apply to the children.

[GuillaumeGomez]

Modules can be used as code namespaces (which is, I think, the most common thing). Adding a code example on something like that doesn't make sense, since it's just providing a set of functions/types. Which one should you pick? It doesn't make sense.

[Manishearth]

When modules are used as code namespaces they are private with reexported members. If the module is public, it's being used as a proper namespace.

[Manishearth]

Like, I'm struggling to come up with a project I have worked on where there is no applicable code example on the module, aside from grab-bag utility modules, or modules containing a lot of subparts (e.g. std).

[GuillaumeGomez]

Yes, I realized it afterwards (forgot to write it here, just talked about that with @jyn514 on discord...).

[jyn514]

So the discussion is in one place: what we discussed is that we were talking at cross-purposes. @GuillaumeGomez was only referring to private modules and both @Manishearth and I thought he was talking about public modules. @GuillaumeGomez plans to make a few other PRs that make the handling of private vs public lints in rustdoc more consistent (of which I think #76767 is the first).

[bors]

☔ The latest upstream changes (presumably #76804) made this pull request unmergeable. Please resolve the merge conflicts.

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

[jyn514]

@GuillaumeGomez does this still make sense to add? I think the discussion about missing_docs being consistent with or without --document-private-items is also true here: I would expect a separate lint for warning about private items, instead of it changing behavior based on a CLI argument.

[GuillaumeGomez]

No, indeed! Closing.