1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
use rustc_data_structures::fx::FxHashMap;
use rustc_lint::LintStore;
use rustc_lint_defs::{declare_tool_lint, Lint, LintId};
use rustc_session::{lint, Session};
use std::sync::LazyLock as Lazy;
/// This function is used to setup the lint initialization. By default, in rustdoc, everything
/// is "allowed". Depending if we run in test mode or not, we want some of them to be at their
/// default level. For example, the "INVALID_CODEBLOCK_ATTRIBUTES" lint is activated in both
/// modes.
///
/// A little detail easy to forget is that there is a way to set the lint level for all lints
/// through the "WARNINGS" lint. To prevent this to happen, we set it back to its "normal" level
/// inside this function.
///
/// It returns a tuple containing:
/// * Vector of tuples of lints' name and their associated "max" level
/// * HashMap of lint id with their associated "max" level
pub(crate) fn init_lints<F>(
mut allowed_lints: Vec<String>,
lint_opts: Vec<(String, lint::Level)>,
filter_call: F,
) -> (Vec<(String, lint::Level)>, FxHashMap<lint::LintId, lint::Level>)
where
F: Fn(&lint::Lint) -> Option<(String, lint::Level)>,
{
let warnings_lint_name = lint::builtin::WARNINGS.name;
allowed_lints.push(warnings_lint_name.to_owned());
allowed_lints.extend(lint_opts.iter().map(|(lint, _)| lint).cloned());
let lints = || {
lint::builtin::HardwiredLints::get_lints()
.into_iter()
.chain(rustc_lint::SoftLints::get_lints().into_iter())
};
let lint_opts = lints()
.filter_map(|lint| {
// Permit feature-gated lints to avoid feature errors when trying to
// allow all lints.
if lint.feature_gate.is_some() || allowed_lints.iter().any(|l| lint.name == l) {
None
} else {
filter_call(lint)
}
})
.chain(lint_opts.into_iter())
.collect::<Vec<_>>();
let lint_caps = lints()
.filter_map(|lint| {
// We don't want to allow *all* lints so let's ignore
// those ones.
if allowed_lints.iter().any(|l| lint.name == l) {
None
} else {
Some((lint::LintId::of(lint), lint::Allow))
}
})
.collect();
(lint_opts, lint_caps)
}
macro_rules! declare_rustdoc_lint {
(
$(#[$attr:meta])* $name: ident, $level: ident, $descr: literal $(,)?
$(@feature_gate = $gate:expr;)?
) => {
declare_tool_lint! {
$(#[$attr])* pub rustdoc::$name, $level, $descr
$(, @feature_gate = $gate;)?
}
}
}
declare_rustdoc_lint! {
/// The `broken_intra_doc_links` lint detects failures in resolving
/// intra-doc link targets. This is a `rustdoc` only lint, see the
/// documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#broken_intra_doc_links
BROKEN_INTRA_DOC_LINKS,
Warn,
"failures in resolving intra-doc link targets"
}
declare_rustdoc_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
PRIVATE_INTRA_DOC_LINKS,
Warn,
"linking from a public item to a private one"
}
declare_rustdoc_lint! {
/// The `invalid_codeblock_attributes` lint detects code block attributes
/// in documentation examples that have potentially mis-typed values. This
/// is a `rustdoc` only lint, see the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#invalid_codeblock_attributes
INVALID_CODEBLOCK_ATTRIBUTES,
Warn,
"codeblock attribute looks a lot like a known one"
}
declare_rustdoc_lint! {
/// The `missing_crate_level_docs` lint detects if documentation is
/// missing at the crate root. This is a `rustdoc` only lint, see the
/// documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#missing_crate_level_docs
MISSING_CRATE_LEVEL_DOCS,
Allow,
"detects crates with no crate-level documentation"
}
declare_rustdoc_lint! {
/// The `missing_doc_code_examples` lint detects publicly-exported items
/// without code samples in their documentation. This is a `rustdoc` only
/// lint, see the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#missing_doc_code_examples
MISSING_DOC_CODE_EXAMPLES,
Allow,
"detects publicly-exported items without code samples in their documentation",
@feature_gate = rustc_span::symbol::sym::rustdoc_missing_doc_code_examples;
}
declare_rustdoc_lint! {
/// The `private_doc_tests` lint detects code samples in docs of private
/// items not documented by `rustdoc`. This is a `rustdoc` only lint, see
/// the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#private_doc_tests
PRIVATE_DOC_TESTS,
Allow,
"detects code samples in docs of private items not documented by rustdoc"
}
declare_rustdoc_lint! {
/// The `invalid_html_tags` lint detects invalid HTML tags. This is a
/// `rustdoc` only lint, see the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#invalid_html_tags
INVALID_HTML_TAGS,
Warn,
"detects invalid HTML tags in doc comments"
}
declare_rustdoc_lint! {
/// The `bare_urls` lint detects when a URL is not a hyperlink.
/// This is a `rustdoc` only lint, see the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#bare_urls
BARE_URLS,
Warn,
"detects URLs that are not hyperlinks"
}
declare_rustdoc_lint! {
/// The `invalid_rust_codeblocks` lint detects Rust code blocks in
/// documentation examples that are invalid (e.g. empty, not parsable as
/// Rust code). This is a `rustdoc` only lint, see the documentation in the
/// [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#invalid_rust_codeblocks
INVALID_RUST_CODEBLOCKS,
Warn,
"codeblock could not be parsed as valid Rust or is empty"
}
pub(crate) static RUSTDOC_LINTS: Lazy<Vec<&'static Lint>> = Lazy::new(|| {
vec![
BROKEN_INTRA_DOC_LINKS,
PRIVATE_INTRA_DOC_LINKS,
MISSING_DOC_CODE_EXAMPLES,
PRIVATE_DOC_TESTS,
INVALID_CODEBLOCK_ATTRIBUTES,
INVALID_RUST_CODEBLOCKS,
INVALID_HTML_TAGS,
BARE_URLS,
MISSING_CRATE_LEVEL_DOCS,
]
});
pub(crate) fn register_lints(_sess: &Session, lint_store: &mut LintStore) {
lint_store.register_lints(&**RUSTDOC_LINTS);
lint_store.register_group(
true,
"rustdoc::all",
Some("rustdoc"),
RUSTDOC_LINTS.iter().map(|&lint| LintId::of(lint)).collect(),
);
for lint in &*RUSTDOC_LINTS {
let name = lint.name_lower();
lint_store.register_renamed(&name.replace("rustdoc::", ""), &name);
}
lint_store
.register_renamed("intra_doc_link_resolution_failure", "rustdoc::broken_intra_doc_links");
lint_store.register_renamed("non_autolinks", "rustdoc::bare_urls");
lint_store.register_renamed("rustdoc::non_autolinks", "rustdoc::bare_urls");
}
|
