mirror of
https://github.com/rust-lang/rust.git
synced 2024-11-24 15:54:15 +00:00
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:
commit
2a90d31423
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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.
|
||||||
|
@ -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(¬e);
|
diag.note(¬e);
|
||||||
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");
|
||||||
}
|
}
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
6
src/test/rustdoc/intra-doc-link-private.rs
Normal file
6
src/test/rustdoc/intra-doc-link-private.rs
Normal 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;
|
Loading…
Reference in New Issue
Block a user