Rollup merge of #77249 - jyn514:private-links, r=Manishearth

Separate `private_intra_doc_links` and `broken_intra_doc_links` into separate lints

This is not ideal because it means `deny(broken_intra_doc_links)` will
no longer `deny(private_intra_doc_links)`. However, it can't be fixed
with a new lint group, because `broken` is already in the `rustdoc` lint
group; there would need to be a way to nest groups somehow.

This also removes the early `return` so that the link will be generated
even though it gives a warning.

r? @Manishearth
cc @ecstatic-morse (https://github.com/rust-lang/rust/pull/77242#issuecomment-699565095)
This commit is contained in:
Jonas Schievink 2020-09-27 18:37:23 +02:00 committed by GitHub
commit 2a90d31423
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 75 additions and 12 deletions

View File

@ -305,6 +305,7 @@ fn register_builtins(store: &mut LintStore, no_interleave_lints: bool) {
add_lint_group!( add_lint_group!(
"rustdoc", "rustdoc",
BROKEN_INTRA_DOC_LINKS, BROKEN_INTRA_DOC_LINKS,
PRIVATE_INTRA_DOC_LINKS,
INVALID_CODEBLOCK_ATTRIBUTES, INVALID_CODEBLOCK_ATTRIBUTES,
MISSING_DOC_CODE_EXAMPLES, MISSING_DOC_CODE_EXAMPLES,
PRIVATE_DOC_TESTS PRIVATE_DOC_TESTS

View File

@ -1826,6 +1826,17 @@ declare_lint! {
"failures in resolving intra-doc link targets" "failures in resolving intra-doc link targets"
} }
declare_lint! {
/// This is a subset of `broken_intra_doc_links` that warns when linking from
/// a public item to a private one. This is a `rustdoc` only lint, see the
/// documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#private_intra_doc_links
pub PRIVATE_INTRA_DOC_LINKS,
Warn,
"linking from a public item to a private one"
}
declare_lint! { declare_lint! {
/// The `invalid_codeblock_attributes` lint detects code block attributes /// The `invalid_codeblock_attributes` lint detects code block attributes
/// in documentation examples that have potentially mis-typed values. This /// in documentation examples that have potentially mis-typed values. This

View File

@ -62,6 +62,46 @@ help: to link to the function, add parentheses
``` ```
## private_intra_doc_links
This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
For example:
```rust
/// [private]
pub fn public() {}
fn private() {}
```
This gives a warning that the link will be broken when it appears in your documentation:
```text
warning: public documentation for `public` links to private item `private`
--> priv.rs:1:6
|
1 | /// [private]
| ^^^^^^^ this item is private
|
= note: `#[warn(private_intra_doc_links)]` on by default
= note: this link will resolve properly if you pass `--document-private-items`
```
Note that this has different behavior depending on whether you pass `--document-private-items` or not!
If you document private items, then it will still generate a link, despite the warning:
```text
warning: public documentation for `public` links to private item `private`
--> priv.rs:1:6
|
1 | /// [private]
| ^^^^^^^ this item is private
|
= note: `#[warn(private_intra_doc_links)]` on by default
= note: this link resolves only because you passed `--document-private-items`, but will break without
```
[intra-doc links]: linking-to-items-by-name.html
## missing_docs ## missing_docs
This lint is **allowed by default**. It detects items missing documentation. This lint is **allowed by default**. It detects items missing documentation.

View File

@ -11,7 +11,10 @@ use rustc_hir::def::{
use rustc_hir::def_id::DefId; use rustc_hir::def_id::DefId;
use rustc_middle::ty; use rustc_middle::ty;
use rustc_resolve::ParentScope; use rustc_resolve::ParentScope;
use rustc_session::lint; use rustc_session::lint::{
builtin::{BROKEN_INTRA_DOC_LINKS, PRIVATE_INTRA_DOC_LINKS},
Lint,
};
use rustc_span::hygiene::MacroKind; use rustc_span::hygiene::MacroKind;
use rustc_span::symbol::Ident; use rustc_span::symbol::Ident;
use rustc_span::symbol::Symbol; use rustc_span::symbol::Symbol;
@ -988,7 +991,7 @@ impl LinkCollector<'_, '_> {
let report_mismatch = |specified: Disambiguator, resolved: Disambiguator| { let report_mismatch = |specified: Disambiguator, resolved: Disambiguator| {
// The resolved item did not match the disambiguator; give a better error than 'not found' // The resolved item did not match the disambiguator; give a better error than 'not found'
let msg = format!("incompatible link kind for `{}`", path_str); let msg = format!("incompatible link kind for `{}`", path_str);
report_diagnostic(cx, &msg, &item, dox, &link_range, |diag, sp| { let callback = |diag: &mut DiagnosticBuilder<'_>, sp| {
let note = format!( let note = format!(
"this link resolved to {} {}, which is not {} {}", "this link resolved to {} {}, which is not {} {}",
resolved.article(), resolved.article(),
@ -998,7 +1001,8 @@ impl LinkCollector<'_, '_> {
); );
diag.note(&note); diag.note(&note);
suggest_disambiguator(resolved, diag, path_str, dox, sp, &link_range); suggest_disambiguator(resolved, diag, path_str, dox, sp, &link_range);
}); };
report_diagnostic(cx, BROKEN_INTRA_DOC_LINKS, &msg, &item, dox, &link_range, callback);
}; };
if let Res::PrimTy(..) = res { if let Res::PrimTy(..) = res {
match disambiguator { match disambiguator {
@ -1055,7 +1059,6 @@ impl LinkCollector<'_, '_> {
&& !self.cx.tcx.privacy_access_levels(LOCAL_CRATE).is_exported(hir_dst) && !self.cx.tcx.privacy_access_levels(LOCAL_CRATE).is_exported(hir_dst)
{ {
privacy_error(cx, &item, &path_str, dox, link_range); privacy_error(cx, &item, &path_str, dox, link_range);
return;
} }
} }
let id = register_res(cx, res); let id = register_res(cx, res);
@ -1417,6 +1420,7 @@ impl Suggestion {
/// to it. /// to it.
fn report_diagnostic( fn report_diagnostic(
cx: &DocContext<'_>, cx: &DocContext<'_>,
lint: &'static Lint,
msg: &str, msg: &str,
item: &Item, item: &Item,
dox: &str, dox: &str,
@ -1435,7 +1439,7 @@ fn report_diagnostic(
let attrs = &item.attrs; let attrs = &item.attrs;
let sp = span_of_attrs(attrs).unwrap_or(item.source.span()); let sp = span_of_attrs(attrs).unwrap_or(item.source.span());
cx.tcx.struct_span_lint_hir(lint::builtin::BROKEN_INTRA_DOC_LINKS, hir_id, sp, |lint| { cx.tcx.struct_span_lint_hir(lint, hir_id, sp, |lint| {
let mut diag = lint.build(msg); let mut diag = lint.build(msg);
let span = link_range let span = link_range
@ -1482,6 +1486,7 @@ fn resolution_failure(
) { ) {
report_diagnostic( report_diagnostic(
collector.cx, collector.cx,
BROKEN_INTRA_DOC_LINKS,
&format!("unresolved link to `{}`", path_str), &format!("unresolved link to `{}`", path_str),
item, item,
dox, dox,
@ -1695,7 +1700,7 @@ fn anchor_failure(
), ),
}; };
report_diagnostic(cx, &msg, item, dox, &link_range, |diag, sp| { report_diagnostic(cx, BROKEN_INTRA_DOC_LINKS, &msg, item, dox, &link_range, |diag, sp| {
if let Some(sp) = sp { if let Some(sp) = sp {
diag.span_label(sp, "contains invalid anchor"); diag.span_label(sp, "contains invalid anchor");
} }
@ -1734,7 +1739,7 @@ fn ambiguity_error(
} }
} }
report_diagnostic(cx, &msg, item, dox, &link_range, |diag, sp| { report_diagnostic(cx, BROKEN_INTRA_DOC_LINKS, &msg, item, dox, &link_range, |diag, sp| {
if let Some(sp) = sp { if let Some(sp) = sp {
diag.span_label(sp, "ambiguous link"); diag.span_label(sp, "ambiguous link");
} else { } else {
@ -1784,7 +1789,7 @@ fn privacy_error(
let msg = let msg =
format!("public documentation for `{}` links to private item `{}`", item_name, path_str); format!("public documentation for `{}` links to private item `{}`", item_name, path_str);
report_diagnostic(cx, &msg, item, dox, &link_range, |diag, sp| { report_diagnostic(cx, PRIVATE_INTRA_DOC_LINKS, &msg, item, dox, &link_range, |diag, sp| {
if let Some(sp) = sp { if let Some(sp) = sp {
diag.span_label(sp, "this item is private"); diag.span_label(sp, "this item is private");
} }

View File

@ -4,7 +4,7 @@ warning: public documentation for `DocMe` links to private item `DontDocMe`
LL | /// docs [DontDocMe] LL | /// docs [DontDocMe]
| ^^^^^^^^^ this item is private | ^^^^^^^^^ this item is private
| |
= note: `#[warn(broken_intra_doc_links)]` on by default = note: `#[warn(private_intra_doc_links)]` on by default
= note: this link resolves only because you passed `--document-private-items`, but will break without = note: this link resolves only because you passed `--document-private-items`, but will break without
warning: 1 warning emitted warning: 1 warning emitted

View File

@ -4,7 +4,7 @@ warning: public documentation for `DocMe` links to private item `DontDocMe`
LL | /// docs [DontDocMe] LL | /// docs [DontDocMe]
| ^^^^^^^^^ this item is private | ^^^^^^^^^ this item is private
| |
= note: `#[warn(broken_intra_doc_links)]` on by default = note: `#[warn(private_intra_doc_links)]` on by default
= note: this link will resolve properly if you pass `--document-private-items` = note: this link will resolve properly if you pass `--document-private-items`
warning: 1 warning emitted warning: 1 warning emitted

View File

@ -4,7 +4,7 @@ warning: public documentation for `public_item` links to private item `PrivateTy
LL | /// [`PrivateType`] LL | /// [`PrivateType`]
| ^^^^^^^^^^^^^ this item is private | ^^^^^^^^^^^^^ this item is private
| |
= note: `#[warn(broken_intra_doc_links)]` on by default = note: `#[warn(private_intra_doc_links)]` on by default
= note: this link resolves only because you passed `--document-private-items`, but will break without = note: this link resolves only because you passed `--document-private-items`, but will break without
warning: 1 warning emitted warning: 1 warning emitted

View File

@ -4,7 +4,7 @@ warning: public documentation for `public_item` links to private item `PrivateTy
LL | /// [`PrivateType`] LL | /// [`PrivateType`]
| ^^^^^^^^^^^^^ this item is private | ^^^^^^^^^^^^^ this item is private
| |
= note: `#[warn(broken_intra_doc_links)]` on by default = note: `#[warn(private_intra_doc_links)]` on by default
= note: this link will resolve properly if you pass `--document-private-items` = note: this link will resolve properly if you pass `--document-private-items`
warning: 1 warning emitted warning: 1 warning emitted

View File

@ -0,0 +1,6 @@
#![crate_name = "private"]
// compile-flags: --document-private-items
/// docs [DontDocMe]
// @has private/struct.DocMe.html '//*a[@href="../private/struct.DontDocMe.html"]' 'DontDocMe'
pub struct DocMe;
struct DontDocMe;