Skip to content

rustdoc: #[doc(notable_trait)] doesn't work on re-exports #81143

@camelid

Description

@camelid

This code correctly triggers the "Notable traits" dialog:

#![feature(doc_spotlight)]

mod my_module {
    #[doc(spotlight)]
    pub trait MyTrait {}
}

pub use my_module::MyTrait;

pub struct MyStruct;
impl MyTrait for MyStruct {}

pub fn my_function() -> MyStruct { MyStruct }

But this does not:

#![feature(doc_spotlight)]

mod my_module {
    pub trait MyTrait {}
}

#[doc(spotlight)]
pub use my_module::MyTrait;

pub struct MyStruct;
impl MyTrait for MyStruct {}

pub fn my_function() -> MyStruct { MyStruct }

The difference is that the first one puts #[doc(spotlight)] on the trait,
while the second puts it on the re-export. I'm not certain that this is supposed
to work, but there is code in src/librustdoc/clean/inline.rs, which seems to
be used for re-exports, that supposedly detects #[doc(spotlight)]:

crate fn build_external_trait(cx: &DocContext<'_>, did: DefId) -> clean::Trait {
let trait_items =
cx.tcx.associated_items(did).in_definition_order().map(|item| item.clean(cx)).collect();
let predicates = cx.tcx.predicates_of(did);
let generics = (cx.tcx.generics_of(did), predicates).clean(cx);
let generics = filter_non_trait_generics(did, generics);
let (generics, supertrait_bounds) = separate_supertrait_bounds(generics);
let is_spotlight = load_attrs(cx, did).clean(cx).has_doc_flag(sym::spotlight);
let is_auto = cx.tcx.trait_is_auto(did);
clean::Trait {
unsafety: cx.tcx.trait_def(did).unsafety,
generics,
items: trait_items,
bounds: supertrait_bounds,
is_spotlight,
is_auto,
}
}

That build_external_trait function is called in two places, one of which is in
the try_inline function:

Res::Def(DefKind::Trait, did) => {
record_extern_fqn(cx, did, clean::TypeKind::Trait);
ret.extend(build_impls(cx, Some(parent_module), did, attrs));
clean::TraitItem(build_external_trait(cx, did))
}

This was discovered in #80965 (comment).

cc @jyn514

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-local-reexportsArea: Documentation that has been locally re-exported (i.e., non-cross-crate)A-trait-systemArea: Trait systemC-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.requires-nightlyThis issue requires a nightly compiler in some way. When possible, use a F-* label instead.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions