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.

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

Beta rustc warns on missing documentation for an extern crate even though the docstring is not used by rustdoc #112308

Closed
elinorbgr opened this issue Jun 5, 2023 · 5 comments · Fixed by #112343
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@elinorbgr
Copy link
Contributor

minimal example:

#![warn(missing_docs)]

pub extern crate alloc;

Running cargo check on this example outputs no warning on stable 1.70.0, but on either rustc 1.71.0-beta.2 (4e8c9e8e3 2023-06-04) or rustc 1.72.0-nightly (101fa903b 2023-06-04) it outputs the following warning:

warning: missing documentation for an extern crate
 --> src/lib.rs:5:1
  |
5 | pub extern crate alloc;
  | ^^^^^^^^^^^^^^^^^^^^^^
  |
note: the lint level is defined here
 --> src/lib.rs:3:9
  |
3 | #![warn(missing_docs)]
  |         ^^^^^^^^^^^^

Adding a docstring does silence the warning, but as far as I can tell this docstring is not used anywhere by rustdoc: adding it has no impact on the generated documentation.

I suppose either the warning is inadequate, or rustdoc should display that docstring.

cc @GuillaumeGomez

@GuillaumeGomez GuillaumeGomez added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Jun 5, 2023
@GuillaumeGomez
Copy link
Member

Thanks for opening the issue! We have a few items where the documentation is ignored. I think for the current case, the best would be to not warn as a first step. Then we should maybe discuss whether or not we want to display documentation for these items and also how. It was suggested some time ago to create pages to list such items (by grouping them). To be discussed.

@jannic
Copy link
Contributor

jannic commented Jul 11, 2023

@GuillaumeGomez, the warning is still present in current beta ,1.71.0-beta.6 (01b5c40dc 2023-07-08).
Should the fix be back-ported, or will rust 1.71.0, when released, emit this warning?

@GuillaumeGomez
Copy link
Member

It should be backported to beta.

@jannic
Copy link
Contributor

jannic commented Jul 11, 2023

I just noticed that 1.71.0 is already in pre-release testing, https://internals.rust-lang.org/t/rust-1-71-0-pre-release-testing/19123
So it's probably too late for a backport, right? 😢

@GuillaumeGomez
Copy link
Member

I don't know, we'll see. If not we can always do a stable backport.

jannic added a commit to jannic/rp-hal that referenced this issue Jul 11, 2023
Due to rust-lang/rust#112308, the public
re-export of the pac will trigger a missing docs warning in rust
1.71.0.

This is bogus, as the doc string would not be shown in the rendered
docs anyway. However, the warning would be annoying, so add a short
doc string to the item.
Mark-Simulacrum pushed a commit to Mark-Simulacrum/rust that referenced this issue Jul 12, 2023
xobs pushed a commit to betrusted-io/rust that referenced this issue Aug 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants