Support #[doc(hidden)] #[macro_export] macro_rules! that are reexported in a place different than the crate root

With some limitations forced on us by the analyzer, as explained in the code.

Author: ChayimFriedman2

crates/hir-expand/src/mod_path.rs

@@ -192,6 +192,15 @@ impl ModPath {
     ) -> impl fmt::Display + 'a {
         Display { db, path: self, edition: Some(edition) }
     }
+
+    pub fn last_name(&self) -> Name {
+        self.segments.last().cloned().unwrap_or_else(|| match self.kind {
+            PathKind::DollarCrate(_) | PathKind::Abs | PathKind::Plain => Name::missing(),
+            PathKind::SELF => Name::new_symbol_root(sym::self_),
+            PathKind::Super(_) => Name::new_symbol_root(sym::super_),
+            PathKind::Crate => Name::new_symbol_root(sym::crate_),
+        })
+    }
 }
 
 impl Extend<Name> for ModPath {

crates/hir/src/attrs.rs

@@ -110,11 +110,42 @@ impl AttrsWithOwner {
         self.attrs.contains(AttrFlags::IS_DOC_NOTABLE_TRAIT)
     }
 
+    /// Never call this for macros.
     #[inline]
-    pub fn is_doc_hidden(&self) -> bool {
+    pub(crate) fn is_doc_hidden_raw(&self) -> bool {
         self.attrs.contains(AttrFlags::IS_DOC_HIDDEN)
     }
 
+    /// This checks whether this item is `#[doc(hidden)]`. However macros are special in this regard:
+    /// we want to treat usages of non-hidden reexports of hidden macros as non-hidden, see [`Macro::legacy_macros_reexport()`].
+    /// We don't have a real semantic way to distinguish between them, so we use the name as an indication.
+    pub fn is_doc_hidden(
+        &self,
+        db: &dyn HirDatabase,
+        under_name: &Name,
+        in_module: Module,
+    ) -> bool {
+        if !self.is_doc_hidden_raw() {
+            return false;
+        }
+
+        if let AttrsOwner::AttrDef(AttrDefId::MacroId(makro)) = self.owner
+            && let Some((reexport_name, reexport)) =
+                (Macro { id: makro }).legacy_macros_reexport(db)
+            && *under_name == reexport_name
+            && reexport.vis.is_visible_from(db, in_module.id)
+        {
+            // Two things are noticeable here:
+            //  1. We don't check whether the reexport has `#[doc(hidden)]`, because we have no easy and performant way
+            //     to check attributes of reexports.
+            //  2. If the reexport has the same name as the macro, we always treat it as non-hidden. We do so because
+            //     it's common to use the same name.
+            return false;
+        }
+
+        true
+    }
+
     #[inline]
     pub fn is_deprecated(&self) -> bool {
         self.attrs.contains(AttrFlags::IS_DEPRECATED)

crates/hir/src/lib.rs

@@ -1810,6 +1810,10 @@ impl EnumVariant {
         );
         InstantiatedVariant { inner: self, args }
     }
+
+    pub fn is_doc_hidden(&self, db: &dyn HirDatabase) -> bool {
+        self.attrs(db).is_doc_hidden_raw()
+    }
 }
 
 // FIXME: Rename to `EnumVariant`
@@ -3516,6 +3520,10 @@ impl Macro {
                 as_name_opt(source.value.name())
             }
             MacroId::MacroRulesId(id) => {
+                if let Some((reexport_name, _)) = self.legacy_macros_reexport(db) {
+                    return reexport_name;
+                }
+
                 let loc = id.lookup(db);
                 let source = loc.source(db);
                 as_name_opt(source.value.name())
@@ -3624,6 +3632,50 @@ impl Macro {
         let attrs = self.attrs(db);
         MacroBraces::extract(attrs.attrs)
     }
+
+    // Feature: Detection of exported `macro_rules!`
+    //
+    // `macro_rules!` macros can only be publicly exported via `#[macro_export]` and at the crate root.
+    // For proper scoping, a common practice is to mark the macro `#[doc(hidden)]`, then have a public reexport
+    // where you want to export the macro. rust-analyzer generally supports this practice and detects the correct
+    // way to call the macro, however as a crate author you must make sure two conditions are fulfilled:
+    //
+    //  1. The reexport is *exactly in the same module* as the macro. If this condition is not fulfilled,
+    //     rust-analyzer will fail to detect the reexport and consider the macro hidden. Of course, you can then
+    //     reexport the reexport wherever you like.
+    //  2. For best experience, the reexport should be renaming. That is, declare the macro with a different name
+    //     than you want (a common practice is to call it `__<my_macro>`) then rename it in the reexport, like
+    //     `pub use __my_macro as my_macro`. If you do not do this, rust-analyzer will still find the reexport,
+    //     but it will also consider the macro not hidden at the crate root.
+
+    /// Legacy (`macro_rules!`) macros cannot have proper namespacing resolution in Rust (more precisely, they
+    /// cannot have it across crates). Therefore, it is a common practice to make a macro `#[doc(hidden)]`
+    /// and put `pub use __macro as macro` in the same module. In such cases, this function will return
+    /// the reexport.
+    fn legacy_macros_reexport(
+        &self,
+        db: &dyn HirDatabase,
+    ) -> Option<(Name, hir_def::per_ns::MacrosItem)> {
+        let MacroId::MacroRulesId(makro) = self.id else {
+            return None;
+        };
+        if !AttrFlags::query(db, makro.into())
+            .contains(AttrFlags::IS_DOC_HIDDEN | AttrFlags::IS_MACRO_EXPORT)
+        {
+            return None;
+        }
+        let loc = makro.loc(db);
+        let def_map = loc.container.def_map(db);
+        if loc.container == def_map.crate_root(db) {
+            // `#[macro_export]` macros defined at the crate root cannot have a reexport,
+            // it'll cause conflicts with the builtin export.
+            return None;
+        }
+        let scope = &def_map[loc.container].scope;
+        let (reexport_name, reexport) =
+            scope.macros().find(|(_, reexport)| reexport.def == self.id)?;
+        Some((reexport_name.clone(), reexport))
+    }
 }
 
 // Feature: Macro Brace Style Attribute
@@ -4036,6 +4088,10 @@ impl AssocItem {
             }
         }
     }
+
+    pub fn is_doc_hidden(&self, db: &dyn HirDatabase) -> bool {
+        self.attrs(db).is_doc_hidden_raw()
+    }
 }
 
 impl HasVisibility for AssocItem {

crates/ide-assists/src/handlers/add_missing_match_arms.rs

@@ -489,7 +489,7 @@ impl ExtendedVariant {
     fn should_be_hidden(self, db: &RootDatabase, krate: Crate) -> bool {
         match self {
             ExtendedVariant::Variant { variant: var, .. } => {
-                var.attrs(db).is_doc_hidden() && var.module(db).krate(db) != krate
+                var.is_doc_hidden(db) && var.module(db).krate(db) != krate
             }
             _ => false,
         }

crates/ide-assists/src/utils.rs

@@ -4,7 +4,7 @@ use std::slice;
 
 pub(crate) use gen_trait_fn_body::gen_trait_fn_body;
 use hir::{
-    HasAttrs as HirHasAttrs, HirDisplay, InFile, ModuleDef, PathResolution, Semantics,
+    HirDisplay, InFile, ModuleDef, PathResolution, Semantics,
     db::{ExpandDatabase, HirDatabase},
 };
 use ide_db::{
@@ -152,7 +152,7 @@ pub fn filter_assoc_items(
         .copied()
         .filter(|assoc_item| {
             if ignore_items == IgnoreAssocItems::DocHiddenAttrPresent
-                && assoc_item.attrs(sema.db).is_doc_hidden()
+                && assoc_item.is_doc_hidden(sema.db)
             {
                 if let hir::AssocItem::Function(f) = assoc_item
                     && !f.has_body(sema.db)

crates/ide-completion/src/completions.rs

@@ -230,7 +230,7 @@ impl Completions {
         resolution: hir::ScopeDef,
         doc_aliases: Vec<syntax::SmolStr>,
     ) {
-        let is_private_editable = match ctx.def_is_visible(&resolution) {
+        let is_private_editable = match ctx.def_is_visible(&resolution, &local_name) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -251,7 +251,7 @@ impl Completions {
         local_name: hir::Name,
         resolution: hir::ScopeDef,
     ) {
-        let is_private_editable = match ctx.def_is_visible(&resolution) {
+        let is_private_editable = match ctx.def_is_visible(&resolution, &local_name) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -300,7 +300,7 @@ impl Completions {
         mac: hir::Macro,
         local_name: hir::Name,
     ) {
-        let is_private_editable = match ctx.is_visible(&mac) {
+        let is_private_editable = match ctx.is_visible(&mac, &local_name) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -321,7 +321,7 @@ impl Completions {
         func: hir::Function,
         local_name: Option<hir::Name>,
     ) {
-        let is_private_editable = match ctx.is_visible(&func) {
+        let is_private_editable = match ctx.is_visible(&func, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -342,9 +342,8 @@ impl Completions {
         dot_access: &DotAccess<'_>,
         func: hir::Function,
         receiver: Option<SmolStr>,
-        local_name: Option<hir::Name>,
     ) {
-        let is_private_editable = match ctx.is_visible(&func) {
+        let is_private_editable = match ctx.is_visible(&func, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -354,7 +353,6 @@ impl Completions {
             RenderContext::new(ctx).private_editable(is_private_editable).doc_aliases(doc_aliases),
             dot_access,
             receiver,
-            local_name,
             func,
         )
         .add_to(self, ctx.db);
@@ -367,7 +365,7 @@ impl Completions {
         func: hir::Function,
         import: LocatedImport,
     ) {
-        let is_private_editable = match ctx.is_visible(&func) {
+        let is_private_editable = match ctx.is_visible(&func, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -380,14 +378,13 @@ impl Completions {
                 .import_to_add(Some(import)),
             dot_access,
             None,
-            None,
             func,
         )
         .add_to(self, ctx.db);
     }
 
     pub(crate) fn add_const(&mut self, ctx: &CompletionContext<'_>, konst: hir::Const) {
-        let is_private_editable = match ctx.is_visible(&konst) {
+        let is_private_editable = match ctx.is_visible(&konst, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -403,7 +400,7 @@ impl Completions {
         ctx: &CompletionContext<'_>,
         type_alias: hir::TypeAlias,
     ) {
-        let is_private_editable = match ctx.is_visible(&type_alias) {
+        let is_private_editable = match ctx.is_visible(&type_alias, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -432,7 +429,7 @@ impl Completions {
         variant: hir::EnumVariant,
         path: hir::ModPath,
     ) {
-        if !ctx.check_stability_and_hidden(variant) {
+        if !ctx.check_stability_and_hidden(variant, &Name::missing()) {
             return;
         }
         if let Some(builder) =
@@ -449,7 +446,7 @@ impl Completions {
         variant: hir::EnumVariant,
         local_name: Option<hir::Name>,
     ) {
-        if !ctx.check_stability_and_hidden(variant) {
+        if !ctx.check_stability_and_hidden(variant, &Name::missing()) {
             return;
         }
         if let PathCompletionCtx { kind: PathKind::Pat { pat_ctx }, .. } = path_ctx {
@@ -473,7 +470,7 @@ impl Completions {
         field: hir::Field,
         ty: &hir::Type<'_>,
     ) {
-        let is_private_editable = match ctx.is_visible(&field) {
+        let is_private_editable = match ctx.is_visible(&field, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -497,7 +494,7 @@ impl Completions {
         path: Option<hir::ModPath>,
         local_name: Option<hir::Name>,
     ) {
-        let is_private_editable = match ctx.is_visible(&strukt) {
+        let is_private_editable = match ctx.is_visible(&strukt, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -520,7 +517,7 @@ impl Completions {
         path: Option<hir::ModPath>,
         local_name: Option<hir::Name>,
     ) {
-        let is_private_editable = match ctx.is_visible(&un) {
+        let is_private_editable = match ctx.is_visible(&un, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,
@@ -575,7 +572,7 @@ impl Completions {
         variant: hir::EnumVariant,
         local_name: Option<hir::Name>,
     ) {
-        if !ctx.check_stability_and_hidden(variant) {
+        if !ctx.check_stability_and_hidden(variant, &Name::missing()) {
             return;
         }
         self.add_opt(render_variant_pat(
@@ -595,7 +592,7 @@ impl Completions {
         variant: hir::EnumVariant,
         path: hir::ModPath,
     ) {
-        if !ctx.check_stability_and_hidden(variant) {
+        if !ctx.check_stability_and_hidden(variant, &Name::missing()) {
             return;
         }
         let path = Some(&path);
@@ -616,7 +613,7 @@ impl Completions {
         strukt: hir::Struct,
         local_name: Option<hir::Name>,
     ) {
-        let is_private_editable = match ctx.is_visible(&strukt) {
+        let is_private_editable = match ctx.is_visible(&strukt, &Name::missing()) {
             Visible::Yes => false,
             Visible::Editable => true,
             Visible::No => return,

crates/ide-completion/src/completions/dot.rs

@@ -69,7 +69,7 @@ pub(crate) fn complete_dot(
                 has_parens,
             );
             complete_methods(ctx, &future_output, &traits_in_scope, |func| {
-                acc.add_method(ctx, &dot_access, func, Some(await_str.clone()), None)
+                acc.add_method(ctx, &dot_access, func, Some(await_str.clone()))
             });
         }
     }
@@ -83,7 +83,7 @@ pub(crate) fn complete_dot(
         has_parens,
     );
     complete_methods(ctx, receiver_ty, &traits_in_scope, |func| {
-        acc.add_method(ctx, dot_access, func, None, None)
+        acc.add_method(ctx, dot_access, func, None)
     });
 
     if ctx.config.enable_auto_iter && !receiver_ty.strip_references().impls_iterator(ctx.db) {
@@ -118,7 +118,7 @@ pub(crate) fn complete_dot(
                 ctx: dot_access.ctx,
             };
             complete_methods(ctx, &iter, &traits_in_scope, |func| {
-                acc.add_method(ctx, &dot_access, func, Some(iter_sym.clone()), None)
+                acc.add_method(ctx, &dot_access, func, Some(iter_sym.clone()))
             });
         }
     }
@@ -191,7 +191,6 @@ pub(crate) fn complete_undotted_self(
             },
             func,
             Some(SmolStr::new_static(param_name)),
-            None,
         )
     });
 }