Skip to content

Commit 7ee9b7a

Browse files
Aaron1011Aaron1011
committed
Use doc comments from 'pub use' statements
Split off from #62855 Currently, rustdoc ignores any doc comments found on 'pub use' statements. As described in issue #58700, this makes it impossible to properly document procedural macros. Any doc comments must be written on the procedural macro definition, which must occur in a dedicated proc-macro crate. This means that any doc comments or doc tests cannot reference items defined in re-exporting crate, despite the fact that such items may be required to use the procedural macro. To solve this issue, this commit allows doc comments to be written on 'pub use' statements. For consistency, this applies to *all* 'pub use' statements, not just those importing procedural macros. When inlining documentation, documentation on 'pub use' statements will be prepended to the documentation of the inlined item. For example, the following items: ```rust mod other_mod { /// Doc comment from definition pub struct MyStruct; } /// Doc comment from 'pub use' /// pub use other_mod::MyStruct; ``` will caues the documentation for the re-export of 'MyStruct' to be rendered as: ``` Doc comment from 'pub use' Doc comment from definition ``` Note the empty line in the 'pub use' doc comments - because doc comments are concatenated as-is, this ensure that the doc comments on the definition start on a new line.
1 parent 0e9b465 commit 7ee9b7a

File tree

5 files changed

+73
-24
lines changed

5 files changed

+73
-24
lines changed

‎src/librustdoc/clean/inline.rs

+43-15
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ use crate::clean::{
2424

2525
use super::Clean;
2626

27+
type Attrs<'hir> = rustc::ty::Attributes<'hir>;
28+
2729
/// Attempt to inline a definition into this AST.
2830
///
2931
/// This function will fetch the definition specified, and if it is
@@ -40,6 +42,7 @@ pub fn try_inline(
4042
cx: &DocContext<'_>,
4143
res: Res,
4244
name: ast::Name,
45+
attrs: Option<Attrs<'_>>,
4346
visited: &mut FxHashSet<DefId>
4447
) -> Option<Vec<clean::Item>> {
4548
let did = if let Some(did) = res.opt_def_id() {
@@ -49,10 +52,13 @@ pub fn try_inline(
4952
};
5053
if did.is_local() { return None }
5154
let mut ret = Vec::new();
55+
56+
let attrs_clone = attrs.clone();
57+
5258
let inner = match res {
5359
Res::Def(DefKind::Trait, did) => {
5460
record_extern_fqn(cx, did, clean::TypeKind::Trait);
55-
ret.extend(build_impls(cx, did));
61+
ret.extend(build_impls(cx, did, attrs));
5662
clean::TraitItem(build_external_trait(cx, did))
5763
}
5864
Res::Def(DefKind::Fn, did) => {
@@ -61,27 +67,27 @@ pub fn try_inline(
6167
}
6268
Res::Def(DefKind::Struct, did) => {
6369
record_extern_fqn(cx, did, clean::TypeKind::Struct);
64-
ret.extend(build_impls(cx, did));
70+
ret.extend(build_impls(cx, did, attrs));
6571
clean::StructItem(build_struct(cx, did))
6672
}
6773
Res::Def(DefKind::Union, did) => {
6874
record_extern_fqn(cx, did, clean::TypeKind::Union);
69-
ret.extend(build_impls(cx, did));
75+
ret.extend(build_impls(cx, did, attrs));
7076
clean::UnionItem(build_union(cx, did))
7177
}
7278
Res::Def(DefKind::TyAlias, did) => {
7379
record_extern_fqn(cx, did, clean::TypeKind::Typedef);
74-
ret.extend(build_impls(cx, did));
80+
ret.extend(build_impls(cx, did, attrs));
7581
clean::TypedefItem(build_type_alias(cx, did), false)
7682
}
7783
Res::Def(DefKind::Enum, did) => {
7884
record_extern_fqn(cx, did, clean::TypeKind::Enum);
79-
ret.extend(build_impls(cx, did));
85+
ret.extend(build_impls(cx, did, attrs));
8086
clean::EnumItem(build_enum(cx, did))
8187
}
8288
Res::Def(DefKind::ForeignTy, did) => {
8389
record_extern_fqn(cx, did, clean::TypeKind::Foreign);
84-
ret.extend(build_impls(cx, did));
90+
ret.extend(build_impls(cx, did, attrs));
8591
clean::ForeignTypeItem
8692
}
8793
// Never inline enum variants but leave them shown as re-exports.
@@ -113,11 +119,15 @@ pub fn try_inline(
113119
}
114120
_ => return None,
115121
};
122+
123+
let target_attrs = load_attrs(cx, did);
124+
let attrs = merge_attrs(cx, target_attrs, attrs_clone);
125+
116126
cx.renderinfo.borrow_mut().inlined.insert(did);
117127
ret.push(clean::Item {
118128
source: cx.tcx.def_span(did).clean(cx),
119129
name: Some(name.clean(cx)),
120-
attrs: load_attrs(cx, did),
130+
attrs,
121131
inner,
122132
visibility: Some(clean::Public),
123133
stability: cx.tcx.lookup_stability(did).clean(cx),
@@ -144,8 +154,8 @@ pub fn try_inline_glob(cx: &DocContext<'_>, res: Res, visited: &mut FxHashSet<De
144154
}
145155
}
146156

147-
pub fn load_attrs(cx: &DocContext<'_>, did: DefId) -> clean::Attributes {
148-
cx.tcx.get_attrs(did).clean(cx)
157+
pub fn load_attrs<'hir>(cx: &DocContext<'hir>, did: DefId) -> Attrs<'hir> {
158+
cx.tcx.get_attrs(did)
149159
}
150160

151161
/// Record an external fully qualified name in the external_paths cache.
@@ -187,7 +197,7 @@ pub fn build_external_trait(cx: &DocContext<'_>, did: DefId) -> clean::Trait {
187197
let generics = (cx.tcx.generics_of(did), &predicates).clean(cx);
188198
let generics = filter_non_trait_generics(did, generics);
189199
let (generics, supertrait_bounds) = separate_supertrait_bounds(generics);
190-
let is_spotlight = load_attrs(cx, did).has_doc_flag(sym::spotlight);
200+
let is_spotlight = load_attrs(cx, did).clean(cx).has_doc_flag(sym::spotlight);
191201
let is_auto = cx.tcx.trait_is_auto(did);
192202
clean::Trait {
193203
auto: auto_trait,
@@ -274,23 +284,41 @@ fn build_type_alias(cx: &DocContext<'_>, did: DefId) -> clean::Typedef {
274284
}
275285
}
276286

277-
pub fn build_impls(cx: &DocContext<'_>, did: DefId) -> Vec<clean::Item> {
287+
pub fn build_impls(cx: &DocContext<'_>, did: DefId, attrs: Option<Attrs<'_>>) -> Vec<clean::Item> {
278288
let tcx = cx.tcx;
279289
let mut impls = Vec::new();
280290

281291
for &did in tcx.inherent_impls(did).iter() {
282-
build_impl(cx, did, &mut impls);
292+
build_impl(cx, did, attrs.clone(), &mut impls);
283293
}
284294

285295
impls
286296
}
287297

288-
pub fn build_impl(cx: &DocContext<'_>, did: DefId, ret: &mut Vec<clean::Item>) {
298+
fn merge_attrs(cx: &DocContext<'_>, attrs: Attrs<'_>, other_attrs: Option<Attrs<'_>>
299+
) -> clean::Attributes {
300+
let mut merged_attrs: Vec<ast::Attribute> = Vec::with_capacity(attrs.len());
301+
// If we have additional attributes (from a re-export),
302+
// always insert them first. This ensure that re-export
303+
// doc comments show up before the original doc comments
304+
// when we render them.
305+
if let Some(a) = other_attrs {
306+
merged_attrs.extend(a.iter().cloned());
307+
}
308+
merged_attrs.extend(attrs.to_vec());
309+
merged_attrs.clean(cx)
310+
}
311+
312+
pub fn build_impl(cx: &DocContext<'_>, did: DefId, attrs: Option<Attrs<'_>>,
313+
ret: &mut Vec<clean::Item>
314+
) {
289315
if !cx.renderinfo.borrow_mut().inlined.insert(did) {
290316
return
291317
}
292318

293-
let attrs = load_attrs(cx, did);
319+
let attrs = merge_attrs(cx, load_attrs(cx, did), attrs);
320+
321+
294322
let tcx = cx.tcx;
295323
let associated_trait = tcx.impl_trait_ref(did);
296324

@@ -416,7 +444,7 @@ fn build_module(
416444
let def_id = item.res.def_id();
417445
if item.vis == ty::Visibility::Public {
418446
if did == def_id || !visited.insert(def_id) { continue }
419-
if let Some(i) = try_inline(cx, item.res, item.ident.name, visited) {
447+
if let Some(i) = try_inline(cx, item.res, item.ident.name, None, visited) {
420448
items.extend(i)
421449
}
422450
}

‎src/librustdoc/clean/mod.rs

+14-6
Original file line numberDiff line numberDiff line change
@@ -2429,7 +2429,7 @@ impl Clean<Item> for ty::AssocItem {
24292429
stability: get_stability(cx, self.def_id),
24302430
deprecation: get_deprecation(cx, self.def_id),
24312431
def_id: self.def_id,
2432-
attrs: inline::load_attrs(cx, self.def_id),
2432+
attrs: inline::load_attrs(cx, self.def_id).clean(cx),
24332433
source: cx.tcx.def_span(self.def_id).clean(cx),
24342434
inner,
24352435
}
@@ -3372,7 +3372,7 @@ impl Clean<Item> for ty::VariantDef {
33723372
};
33733373
Item {
33743374
name: Some(self.ident.clean(cx)),
3375-
attrs: inline::load_attrs(cx, self.def_id),
3375+
attrs: inline::load_attrs(cx, self.def_id).clean(cx),
33763376
source: cx.tcx.def_span(self.def_id).clean(cx),
33773377
visibility: Some(Inherited),
33783378
def_id: self.def_id,
@@ -3856,7 +3856,7 @@ fn build_deref_target_impls(cx: &DocContext<'_>,
38563856
let primitive = match *target {
38573857
ResolvedPath { did, .. } if did.is_local() => continue,
38583858
ResolvedPath { did, .. } => {
3859-
ret.extend(inline::build_impls(cx, did));
3859+
ret.extend(inline::build_impls(cx, did, None));
38603860
continue
38613861
}
38623862
_ => match target.primitive_type() {
@@ -3894,7 +3894,7 @@ fn build_deref_target_impls(cx: &DocContext<'_>,
38943894
};
38953895
if let Some(did) = did {
38963896
if !did.is_local() {
3897-
inline::build_impl(cx, did, ret);
3897+
inline::build_impl(cx, did, None, ret);
38983898
}
38993899
}
39003900
}
@@ -3921,7 +3921,11 @@ impl Clean<Vec<Item>> for doctree::ExternCrate<'_> {
39213921
},
39223922
);
39233923

3924-
if let Some(items) = inline::try_inline(cx, res, self.name, &mut visited) {
3924+
if let Some(items) = inline::try_inline(
3925+
cx, res, self.name,
3926+
Some(rustc::ty::Attributes::Borrowed(self.attrs)),
3927+
&mut visited
3928+
) {
39253929
return items;
39263930
}
39273931
}
@@ -3981,7 +3985,11 @@ impl Clean<Vec<Item>> for doctree::Import<'_> {
39813985
}
39823986
if !denied {
39833987
let mut visited = FxHashSet::default();
3984-
if let Some(items) = inline::try_inline(cx, path.res, name, &mut visited) {
3988+
if let Some(items) = inline::try_inline(
3989+
cx, path.res, name,
3990+
Some(rustc::ty::Attributes::Borrowed(self.attrs)),
3991+
&mut visited
3992+
) {
39853993
return items;
39863994
}
39873995
}

‎src/librustdoc/passes/collect_trait_impls.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ pub fn collect_trait_impls(krate: Crate, cx: &DocContext<'_>) -> Crate {
3030

3131
for &cnum in cx.tcx.crates().iter() {
3232
for &did in cx.tcx.all_trait_implementations(cnum).iter() {
33-
inline::build_impl(cx, did, &mut new_items);
33+
inline::build_impl(cx, did, None, &mut new_items);
3434
}
3535
}
3636

@@ -66,7 +66,7 @@ pub fn collect_trait_impls(krate: Crate, cx: &DocContext<'_>) -> Crate {
6666

6767
for def_id in primitive_impls.iter().filter_map(|&def_id| def_id) {
6868
if !def_id.is_local() {
69-
inline::build_impl(cx, def_id, &mut new_items);
69+
inline::build_impl(cx, def_id, None, &mut new_items);
7070

7171
// FIXME(eddyb) is this `doc(hidden)` check needed?
7272
if !cx.tcx.get_attrs(def_id).lists(sym::doc).has_word(sym::hidden) {
@@ -119,7 +119,7 @@ pub fn collect_trait_impls(krate: Crate, cx: &DocContext<'_>) -> Crate {
119119
for &trait_did in cx.all_traits.iter() {
120120
for &impl_node in cx.tcx.hir().trait_impls(trait_did) {
121121
let impl_did = cx.tcx.hir().local_def_id(impl_node);
122-
inline::build_impl(cx, impl_did, &mut new_items);
122+
inline::build_impl(cx, impl_did, None, &mut new_items);
123123
}
124124
}
125125

‎src/test/rustdoc/inline_cross/add-docs.rs

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// aux-build:add-docs.rs
2+
3+
extern crate inner;
4+
5+
6+
// @has add_docs/struct.MyStruct.html
7+
// @has add_docs/struct.MyStruct.html "Doc comment from 'pub use', Doc comment from definition"
8+
/// Doc comment from 'pub use',
9+
pub use inner::MyStruct;

‎src/test/rustdoc/inline_cross/auxiliary/add-docs.rs

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#![crate_name = "inner"]
2+
3+
/// Doc comment from definition
4+
pub struct MyStruct;

0 commit comments

Comments
 (0)