Use macros for module declarations

[k-nasa]

Motivation

This is code refactoring. Currently, there is a lot of code that declares modules as follows:

#[cfg(feature = "registry")]
#[cfg_attr(docsrs, doc(cfg(feature = "registry")))]
pub use registry::Registry;

#[cfg(feature = "registry")]
#[cfg_attr(docsrs, doc(cfg(feature = "registry")))]
pub fn registry() -> Registry {
    Registry::default()
}

It is verbose to write a module declaration multiple times using the feature attribute. Also, if the definition for the same feature spans multiple places, it will be a little harder to read the code.

Solution

You can combine features attributes in one place by writing as follows. It also eliminates the need to write the same code over and over again.

cfg_registry! {
    pub use registry::Registry;

    pub fn registry() -> Registry {
        Registry::default()
    }
}

f this code is accepted, we will extend the declaration of the module using macros to other files as well as tracing-subscriber/lib.rs.

[jyn514]

You could make this one macro instead of two by taking the feature as a parameter, something like this:

Suggested change

	macro_rules! cfg_fmt {
	($($item:item)*) => {
	$(
	#[cfg(feature = "fmt")]
	#[cfg_attr(docsrs, doc(cfg(feature = "fmt")))]
	$item
	)*
	}
	}
	macro_rules! cfg_fmt {
	(#[feature = $($name: lit) ] $($item:item)*) => {
	$(
	#[cfg(feature = $name)]
	#[cfg_attr(docsrs, doc(cfg(feature = $name)))]
	$item
	)*
	}
	}

[k-nasa]

I fixed it as follows.
9b4f0e3

[hawkw]

I know that in Tokio we've had some issues in the past with some editors' code completion and other features not working when definitions are hidden inside macro expansion. Do you know if that issue is still widespread enough to be a concern about merging this?

[k-nasa]

@halzy I didn't know this issue... I didn't have such issue in my editor. I don't think this change is acceptable if the code completion doesn't work.
However, it felt like a kind of trade-off because it made the code more readable.

[alce]

fwiw, this is not a problem in Intellij anymore

[davidbarsky]

I know that in Tokio we've had some issues in the past with some editors' code completion and other features not working when definitions are hidden inside macro expansion. Do you know if that issue is still widespread enough to be a concern about merging this?

This has been resolved in IntelliJ Rust 0.3 a few months ago. rust-analyzer also supports this sort of macro expansion.

However, I don't believe RLS can expand these macros. I'm personally okay with directing folks to use rust-analyzer, but I know we're going to get inquiries about this.

[hawkw]

If this is no longer an issue for most widely-used IDEs/editors, I'm good with making this change. I don't have a sense for how many people are still using RLS rather than rust-analyzer, but since RLS is likely to be deprecated in favor of rust-analyzer, I don't think it's super important to support it?

[davidbarsky]

Yup, I think telling folks to use rust-analyzer instead of RLS is fine.

[hawkw]

Okay, since it sounds like this shouldn't break most of the commonly used IDEs and editors, I'm good with this change.

I think there are at least a few more places in tracing-subscriber where we could also use this macro, like here:

tracing/tracing-subscriber/src/filter/mod.rs

Lines 5 to 13 in 5fb114f

	#[cfg(feature = "env-filter")]
	mod env;
	mod level;
	pub use self::level::{LevelFilter, ParseError as LevelParseError};
	#[cfg(feature = "env-filter")]
	#[cfg_attr(docsrs, doc(cfg(feature = "env-filter")))]
	pub use self::env::*;

and here:

tracing/tracing-subscriber/src/fmt/format/mod.rs

Lines 25 to 31 in 5fb114f

	#[cfg(feature = "json")]
	mod json;
	use fmt::{Debug, Display};
	#[cfg(feature = "json")]
	#[cfg_attr(docsrs, doc(cfg(feature = "json")))]
	pub use json::*;

Let's change those (and any other places where it might be applicable outside lib.rs) as well?

I would also be open to making the same change in other crates that have a lot of feature flagged code, but it would be fine to do that in separate PRs.

[k-nasa]

I'll open another PR for change other than lib.rs! It will take some time.

[hawkw]

okay, looks good to me --- looking forwards to followups!