rustdoc: doc attributes are not rendered for re-exports

[crumblingstatue]

Source:

/// Re-export of egui. Use this to access egui functionality.
/// 
/// This way, you don't have to declare egui as a dependency, and this will be
/// guaranteed to be the same version as egui-sfml uses.
pub use egui;

Rendering:

If not rendering is intentional, there should be a warning that the doc text won't show up in the rendered version.

meta:
rustdoc 1.59.0-nightly (db9d361a4 2021-11-28)

[jyn514]

Yeah, that seems reasonable.

Unfortunately this is tricky because unused_doc_comments is emitted in rustc but the inlining logic (which determines whether the additional docs are shown) is in rustdoc. So if we'd have to only warn about this in rustdoc, which seems confusing. (I don't want to move the inlining logic to rustc, it's too arbitrary and entangled with various rustdoc hacks).

[jyn514]

@crumblingstatue a workaround for you in the short-term is to use #[doc(inline)] so the docs show up.

[jyn514]

Relevant code:

rust/src/librustdoc/visit_ast.rs

Lines 182 to 269 in 2a9e083

	fn maybe_inline_local(
	&mut self,
	id: hir::HirId,
	res: Res,
	renamed: Option<Symbol>,
	glob: bool,
	om: &mut Module<'tcx>,
	please_inline: bool,
	) -> bool {
	debug!("maybe_inline_local res: {:?}", res);
	let tcx = self.cx.tcx;
	let res_did = if let Some(did) = res.opt_def_id() {
	did
	} else {
	return false;
	};
	let use_attrs = tcx.hir().attrs(id);
	// Don't inline `doc(hidden)` imports so they can be stripped at a later stage.
	let is_no_inline = use_attrs.lists(sym::doc).has_word(sym::no_inline)
	|| use_attrs.lists(sym::doc).has_word(sym::hidden);
	// For cross-crate impl inlining we need to know whether items are
	// reachable in documentation -- a previously unreachable item can be
	// made reachable by cross-crate inlining which we're checking here.
	// (this is done here because we need to know this upfront).
	if !res_did.is_local() && !is_no_inline {
	let attrs = clean::inline::load_attrs(self.cx, res_did);
	let self_is_hidden = attrs.lists(sym::doc).has_word(sym::hidden);
	if !self_is_hidden {
	if let Res::Def(kind, did) = res {
	if kind == DefKind::Mod {
	crate::visit_lib::LibEmbargoVisitor::new(self.cx).visit_mod(did)
	} else {
	// All items need to be handled here in case someone wishes to link
	// to them with intra-doc links
	self.cx.cache.access_levels.map.insert(did, AccessLevel::Public);
	}
	}
	}
	return false;
	}
	let res_hir_id = match res_did.as_local() {
	Some(n) => tcx.hir().local_def_id_to_hir_id(n),
	None => return false,
	};
	let is_private = !self.cx.cache.access_levels.is_public(res_did);
	let is_hidden = inherits_doc_hidden(self.cx.tcx, res_hir_id);
	// Only inline if requested or if the item would otherwise be stripped.
	if (!please_inline && !is_private && !is_hidden) || is_no_inline {
	return false;
	}
	if !self.view_item_stack.insert(res_hir_id) {
	return false;
	}
	let ret = match tcx.hir().get(res_hir_id) {
	Node::Item(&hir::Item { kind: hir::ItemKind::Mod(ref m), .. }) if glob => {
	let prev = mem::replace(&mut self.inlining, true);
	for &i in m.item_ids {
	let i = self.cx.tcx.hir().item(i);
	self.visit_item(i, None, om);
	}
	self.inlining = prev;
	true
	}
	Node::Item(it) if !glob => {
	let prev = mem::replace(&mut self.inlining, true);
	self.visit_item(it, renamed, om);
	self.inlining = prev;
	true
	}
	Node::ForeignItem(it) if !glob => {
	let prev = mem::replace(&mut self.inlining, true);
	self.visit_foreign_item(it, renamed, om);
	self.inlining = prev;
	true
	}
	_ => false,
	};
	self.view_item_stack.remove(&res_hir_id);
	ret
	}

and

rust/src/librustdoc/clean/inline.rs

Lines 27 to 135 in 2a9e083

	/// Attempt to inline a definition into this AST.
	///
	/// This function will fetch the definition specified, and if it is
	/// from another crate it will attempt to inline the documentation
	/// from the other crate into this crate.
	///
	/// This is primarily used for `pub use` statements which are, in general,
	/// implementation details. Inlining the documentation should help provide a
	/// better experience when reading the documentation in this use case.
	///
	/// The returned value is `None` if the definition could not be inlined,
	/// and `Some` of a vector of items if it was successfully expanded.
	///
	/// `parent_module` refers to the parent of the *re-export*, not the original item.
	crate fn try_inline(
	cx: &mut DocContext<'_>,
	parent_module: DefId,
	import_def_id: Option<DefId>,
	res: Res,
	name: Symbol,
	attrs: Option<Attrs<'_>>,
	visited: &mut FxHashSet<DefId>,
	) -> Option<Vec<clean::Item>> {
	let did = res.opt_def_id()?;
	if did.is_local() {
	return None;
	}
	let mut ret = Vec::new();
	debug!("attrs={:?}", attrs);
	let attrs_clone = attrs;
	let kind = match res {
	Res::Def(DefKind::Trait, did) => {
	record_extern_fqn(cx, did, ItemType::Trait);
	build_impls(cx, Some(parent_module), did, attrs, &mut ret);
	clean::TraitItem(build_external_trait(cx, did))
	}
	Res::Def(DefKind::Fn, did) => {
	record_extern_fqn(cx, did, ItemType::Function);
	clean::FunctionItem(build_external_function(cx, did))
	}
	Res::Def(DefKind::Struct, did) => {
	record_extern_fqn(cx, did, ItemType::Struct);
	build_impls(cx, Some(parent_module), did, attrs, &mut ret);
	clean::StructItem(build_struct(cx, did))
	}
	Res::Def(DefKind::Union, did) => {
	record_extern_fqn(cx, did, ItemType::Union);
	build_impls(cx, Some(parent_module), did, attrs, &mut ret);
	clean::UnionItem(build_union(cx, did))
	}
	Res::Def(DefKind::TyAlias, did) => {
	record_extern_fqn(cx, did, ItemType::Typedef);
	build_impls(cx, Some(parent_module), did, attrs, &mut ret);
	clean::TypedefItem(build_type_alias(cx, did), false)
	}
	Res::Def(DefKind::Enum, did) => {
	record_extern_fqn(cx, did, ItemType::Enum);
	build_impls(cx, Some(parent_module), did, attrs, &mut ret);
	clean::EnumItem(build_enum(cx, did))
	}
	Res::Def(DefKind::ForeignTy, did) => {
	record_extern_fqn(cx, did, ItemType::ForeignType);
	build_impls(cx, Some(parent_module), did, attrs, &mut ret);
	clean::ForeignTypeItem
	}
	// Never inline enum variants but leave them shown as re-exports.
	Res::Def(DefKind::Variant, _) => return None,
	// Assume that enum variants and struct types are re-exported next to
	// their constructors.
	Res::Def(DefKind::Ctor(..), _) | Res::SelfCtor(..) => return Some(Vec::new()),
	Res::Def(DefKind::Mod, did) => {
	record_extern_fqn(cx, did, ItemType::Module);
	clean::ModuleItem(build_module(cx, did, visited))
	}
	Res::Def(DefKind::Static, did) => {
	record_extern_fqn(cx, did, ItemType::Static);
	clean::StaticItem(build_static(cx, did, cx.tcx.is_mutable_static(did)))
	}
	Res::Def(DefKind::Const, did) => {
	record_extern_fqn(cx, did, ItemType::Constant);
	clean::ConstantItem(build_const(cx, did))
	}
	Res::Def(DefKind::Macro(kind), did) => {
	let mac = build_macro(cx, did, name, import_def_id);
	let type_kind = match kind {
	MacroKind::Bang => ItemType::Macro,
	MacroKind::Attr => ItemType::ProcAttribute,
	MacroKind::Derive => ItemType::ProcDerive,
	};
	record_extern_fqn(cx, did, type_kind);
	mac
	}
	_ => return None,
	};
	let (attrs, cfg) = merge_attrs(cx, Some(parent_module), load_attrs(cx, did), attrs_clone);
	cx.inlined.insert(did.into());
	let mut item =
	clean::Item::from_def_id_and_attrs_and_parts(did, Some(name), kind, box attrs, cx, cfg);
	if let Some(import_def_id) = import_def_id {
	// The visibility needs to reflect the one from the reexport and not from the "source" DefId.
	item.visibility = cx.tcx.visibility(import_def_id).clean(cx);
	}
	ret.push(item);
	Some(ret)
	}

[crumblingstatue]

@crumblingstatue a workaround for you in the short-term is to use #[doc(inline)] so the docs show up.

Thank you, that indeed works!