Tracking issue for #[doc(cfg(…))], #[doc(cfg_hide(…))] and doc_auto_cfg

[kennytm]

This is a tracking issue for the #[doc(cfg(…))] attribute (feature: doc_cfg) introduced in #43348 and #[doc(cfg_hide(…))] (feature: doc_cfg_hide) attribute introduced in #89596, along with the doc_auto_cfg feature introduced in #90502.

Steps:

• Implement: Expose all OS-specific modules in libstd doc. #43348
• Fix syntax mismatches: Rustdoc and rustc accept different cfg syntax #84437 (fixed in Unify rustc and rustdoc parsing of cfg() #84442)
• Adjust documentation (see instructions on forge) (Update documentation for doc_cfg feature #92818)
• Stabilization PR (see instructions on forge): Stabilize doc_cfg feature #79263

(cc #1998)

[sfackler]

#[cfg(rustdoc)] is also gated on this issue but seems distinct (and less risky). Could we FCP that portion in particular?

[asomers]

I think that #[cfg(rustdoc)], when applied to structs, should automatically skip any non-public members. That would greatly reduce the amount of extra typing required by crates like Nix.

[Nemo157]

I was just trying this out for documenting crate features, it "works" but if this is a potential usecase it would be nice to special case the rendering for it:

---

---

[Nemo157]

There is also the issue that it repeats every feature on every item in a page:

When I last attempted to do something about rendering features I found it much more useful to separately keep track of "all required features" to render at the top of the items page and "newly introduced features" to render on the sub-items on the page, so you don't get this distracting repetition on every item.

[dtolnay]

We tried out this feature in Syn (dtolnay/syn#734) and decided against using it yet.

What I am happy with

I like how the message turns out at the top of the doc page of a single type or function.

We had previously displayed this information using an italicized note, which was less noticeable.

What I am not happy with

Our index page becomes extremely noisy. I wish there were a way to not show all of these in our case. It is enough to have this information on the type's individual page. Cfg combinations are not among the most important information to show on the index page.

Also inheriting the same note onto every public field seems unnecessary in our use case.

[GuillaumeGomez]

We'll need #103300 to be fixed beforehand as well.

[daxpedda]

I noticed in gfx-rs/wgpu#4935 (comment) that it would be very nice if we could add custom names to cfgs. This is currently done by Rustdoc for known cfgs here:

rust/src/librustdoc/clean/cfg.rs

Lines 488 to 590 in 2b1365b

	Cfg::Cfg(name, value) => {
	let human_readable = match (name, value) {
	(sym::unix, None) => "Unix",
	(sym::windows, None) => "Windows",
	(sym::debug_assertions, None) => "debug-assertions enabled",
	(sym::target_os, Some(os)) => match os.as_str() {
	"android" => "Android",
	"dragonfly" => "DragonFly BSD",
	"emscripten" => "Emscripten",
	"freebsd" => "FreeBSD",
	"fuchsia" => "Fuchsia",
	"haiku" => "Haiku",
	"hermit" => "HermitCore",
	"illumos" => "illumos",
	"ios" => "iOS",
	"l4re" => "L4Re",
	"linux" => "Linux",
	"macos" => "macOS",
	"netbsd" => "NetBSD",
	"openbsd" => "OpenBSD",
	"redox" => "Redox",
	"solaris" => "Solaris",
	"tvos" => "tvOS",
	"wasi" => "WASI",
	"watchos" => "watchOS",
	"windows" => "Windows",
	_ => "",
	},
	(sym::target_arch, Some(arch)) => match arch.as_str() {
	"aarch64" => "AArch64",
	"arm" => "ARM",
	"loongarch64" => "LoongArch LA64",
	"m68k" => "M68k",
	"csky" => "CSKY",
	"mips" => "MIPS",
	"mips32r6" => "MIPS Release 6",
	"mips64" => "MIPS-64",
	"mips64r6" => "MIPS-64 Release 6",
	"msp430" => "MSP430",
	"powerpc" => "PowerPC",
	"powerpc64" => "PowerPC-64",
	"riscv32" => "RISC-V RV32",
	"riscv64" => "RISC-V RV64",
	"s390x" => "s390x",
	"sparc64" => "SPARC64",
	"wasm32" | "wasm64" => "WebAssembly",
	"x86" => "x86",
	"x86_64" => "x86-64",
	_ => "",
	},
	(sym::target_vendor, Some(vendor)) => match vendor.as_str() {
	"apple" => "Apple",
	"pc" => "PC",
	"sun" => "Sun",
	"fortanix" => "Fortanix",
	_ => "",
	},
	(sym::target_env, Some(env)) => match env.as_str() {
	"gnu" => "GNU",
	"msvc" => "MSVC",
	"musl" => "musl",
	"newlib" => "Newlib",
	"uclibc" => "uClibc",
	"sgx" => "SGX",
	_ => "",
	},
	(sym::target_endian, Some(endian)) => return write!(fmt, "{endian}-endian"),
	(sym::target_pointer_width, Some(bits)) => return write!(fmt, "{bits}-bit"),
	(sym::target_feature, Some(feat)) => match self.1 {
	Format::LongHtml => {
	return write!(fmt, "target feature <code>{feat}</code>");
	}
	Format::LongPlain => return write!(fmt, "target feature `{feat}`"),
	Format::ShortHtml => return write!(fmt, "<code>{feat}</code>"),
	},
	(sym::feature, Some(feat)) => match self.1 {
	Format::LongHtml => {
	return write!(fmt, "crate feature <code>{feat}</code>");
	}
	Format::LongPlain => return write!(fmt, "crate feature `{feat}`"),
	Format::ShortHtml => return write!(fmt, "<code>{feat}</code>"),
	},
	_ => "",
	};
	if !human_readable.is_empty() {
	fmt.write_str(human_readable)
	} else if let Some(v) = value {
	if self.1.is_html() {
	write!(
	fmt,
	r#"<code>{}="{}"</code>"#,
	Escape(name.as_str()),
	Escape(v.as_str())
	)
	} else {
	write!(fmt, r#"`{name}="{v}"`"#)
	}
	} else if self.1.is_html() {
	write!(fmt, "<code>{}</code>", Escape(name.as_str()))
	} else {
	write!(fmt, "`{name}`")
	}
	}

Maybe something like doc(cfg_rename(foo = "Foo"))?

[Kixunil]

I just found this doesn't appear to support version(..) cfg. I currently workaround the lack of version predicate by having a build script detect the rustc version and output a cfg. I thought adding #[cfg_attr(docsrs, doc(cfg(any(feature = "std", version("1.77.0")))))] would cause it to render properly but it just fails to build with "invalid predicate" message. I tried adding #![feature(cfg_version)] without any luck.

[GuillaumeGomez]

version(...) is an internal rustc attribute, so it's not supposed to be used outside of std.

[Kixunil]

It isn't, see #64796

[GuillaumeGomez]

This issue is 5 years old and doesn't seem to have been updated much since then. And the only place where the attribute is used is in std libs. However it can be used with a nightly rustc:

#[cfg(version = "1.70.0")]
fn foo() {}

fn main() {}

gives:

error[E0658]: `cfg(version)` is experimental and subject to change
 --> src/main.rs:1:7
  |
1 | #[cfg(version = "1.70.0")]
  |       ^^^^^^^^^^^^^^^^^^
  |
  = note: see issue #64796 <https://github.com/rust-lang/rust/issues/64796> for more information

For more information about this error, try `rustc --explain E0658`.

But in any case, until there is a clear position on whether or not this attribute should be rustc internal only or not, I don't think there is anything to be done.

[Kixunil]

The issue I linked is literally a tracking issue for an accepted RFC. It's not internal, it's supposed to be usable in nightly with syntax version("1.77.0"), not version = "1.77.0". It should be processed by rustdoc correctly to give us a view how things might look once both features are stable.

[jhpratt]

@GuillaumeGomez frankly I have no idea what you're thinking of, but you're unquestionably confusing two different features.

[GuillaumeGomez]

Likely yes...

[clarfonthey]

Just poking around: it appears that the doc_auto_cfg feature links here, but there's no docs in the unstable book for it and the feature doesn't seem to match what's proposed in the RFC. Is this just not implemented, or is the syntax different and this just isn't documented?

[GuillaumeGomez]

The RFC (which is still under discussion so maybe not its final form) proposes something slightly different than what's currently implemented and adds more attributes to give more control.

Currently, to enable this feature, you use #![doc(auto_cfg)] and that's it.