Doctests don't run on nonexported macro_rules! macros

@jyn514

At present, doctests aren't run on macro_rules! macros that are not annotated with #[macro_export]. After #88019, it will become possible to fix this problem. However, doing so will cause tests to run that were skipped previously to run, which will likely cause test failures and may mess up people's CI. It might be helpful to provide some form of warning period first.

The relevant code is here:

rust/src/librustdoc/doctest.rs

Lines 1175 to 1184 in 5eacec9

    
           hir::ItemKind::Macro(ref macro_def) => { 
        
               // FIXME(#88038): Non exported macros have historically not been tested, 
        
               // but we really ought to start testing them. 
        
               let def_id = item.def_id.to_def_id(); 
        
               if macro_def.macro_rules && !self.tcx.has_attr(def_id, sym::macro_export) { 
        
                   intravisit::walk_item(self, item); 
        
                   return; 
        
               } 
        
               item.ident.to_string() 
        
           }

Fixing this issue technically just requires removing that special case. However, things are complicated by the fact that this will cause people's tests to suddenly fail. I'm not really sure how we should handle that. @jyn514, do you have any ideas?

See also https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/.E2.9C.94.20Doctests.20on.20private.20macros.

I think we should just change this; it's no different than #66059 in that the code was already broken before and we just didn't happen to run it. If you're really worried we can do a crater run but I would honestly be ok with just landing this.

@rustbot

@rustbot label +E-easy +E-mentor

Looks like #88019 accidentally prevented these doctests from being run even if --document-private-items is passed :(

@rustbot

@rustbot claim

Rollup merge of rust-lang#96630 - m-ysk:fix/issue-88038, r=notriddle

Auto merge of rust-lang#96630 - m-ysk:fix/issue-88038, r=notriddle

FYI, rayon has an internal macro with an example that wasn't ready to be treated as a test:
https://github.com/rayon-rs/rayon/blob/9dc52d76b12f3da13b87dd509ff29a801177b8d3/src/delegate.rs#L14-L19

... discovered by failing in a CI run.

Hmm, I'm not even sure how to turn that into a working doctest, because the macro isn't exported.

The ignore(cannot-test-this-because-non-exported-macro) in #96630 is also telling -- then what's the point?

Navigation Menu

Repository navigation

Doctests don't run on nonexported `macro_rules!` macros #88038

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	hir::ItemKind::Macro(ref macro_def) => {
	// FIXME(#88038): Non exported macros have historically not been tested,
	// but we really ought to start testing them.
	let def_id = item.def_id.to_def_id();
	if macro_def.macro_rules && !self.tcx.has_attr(def_id, sym::macro_export) {
	intravisit::walk_item(self, item);
	return;
	}
	item.ident.to_string()
	}

Doctests don't run on nonexported macro_rules! macros #88038

Description

Activity

jyn514 commented on Aug 16, 2021

jyn514 commented on Aug 29, 2021

jyn514 commented on Apr 5, 2022

jyn514 commented on Apr 5, 2022

m-ysk commented on May 2, 2022

cuviper commented on May 12, 2022

cuviper commented on May 12, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Doctests don't run on nonexported `macro_rules!` macros #88038