doc_cfg

[kloenk]

I would like to use doc_cfg for documentation. I don't have a clue about the current build system. Would it be trivial to allow? @ojeda can you do that? Also, is this allowed, or would it be a to unstable feature?

[kloenk]

I figured out that I can just enable it (in #439). But We should discuss if I'm allowed to use it :-)

[ojeda]

Not sure what you mean by allowing it in the current build system -- all unstable features are allowed inside rust/, so you should not need any change in particular.

The big question is, as usual, whether to add it to the list of unstable features or not. While for "custom" docs (i.e. docs generated for a given .config) it is fine to skip things that are not enabled, for the "global" docs, i.e. those that we will put in kernel.org, it would definitely nice to document everything. And I assume the "global" docs are the ones that most people will read.

From a quick look, there is still discussion going around doc_cfg, including talk about automatically inferring the doc(cfg(...)) attributes from the usual ones (to avoid duplication) etc., so there are things that may change and may take a while to get stabilized. On the other hand, it seems the feature will get stabilized one way or the other.

Ideally the compiler would ignore this feature when not generating the docs (so that it would not "count" as an unstable feature when not generating docs).

I have taken a look at the generated docs for something like:

#[cfg(any(CONFIG_SYSCTL, doc))]
#[doc(cfg(CONFIG_SYSCTL))]
pub mod sysctl;

and it looks very nice!

[ojeda]

Actually, that gives me an idea: rustdoc could have a way to provide it with a custom map with the "nicer names" (like it has, hardcoded, for some key-values e.g. unix -> "Unix").

On our side, we could then automatically fill it with the titles from Kconfig, or something like that. For instance, for CONFIG_NET we could have the banner with:

This is supported when Networking (CONFIG_NET) is enabled only.

instead of:

This is supported on CONFIG_NET only.

(It looks worse here than in the generated docs).

[nbdd0121]

The big question is, as usual, whether to add it to the list of unstable features or not.

Given that we pin to a specify Rust version, I think we could be more liberal when it comes to use unstable features that wouldn't be difficult to remove in the future. For things like doc_cfg even it's gone from rustc, we can remove all usages easily, so I don't think it'll be problematic to use it.

Actually, that gives me an idea: rustdoc could have a way to provide it with a custom map with the "nicer names" (like it has, hardcoded, for some key-values e.g. unix -> "Unix").

On our side, we could then automatically fill it with the titles from Kconfig, or something like that. For instance, for CONFIG_NET we could have the banner with:

Supported only when Networking support (CONFIG_NET) is enabled.

instead of:

This is supported on CONFIG_NET only.

Sounds like something doable by some simple text postprocessing :)

[ojeda]

Given that we pin to a specify Rust version, I think we could be more liberal when it comes to use unstable features that wouldn't be difficult to remove in the future. For things like doc_cfg even it's gone from rustc, we can remove all usages easily, so I don't think it'll be problematic to use it.

The problem is not so much about removing them (which introduces churn, specially in mainline, but it is not a big deal), but about getting sooner to the point where we can compile the kernel without unstable features. In general, we should see the pinning as temporary, and work towards avoiding it, rather than the opposite (i.e. adding more features :)

Sounds like something doable by some simple text postprocessing :)

Definitely! I usually try to describe things in terms of what upstream could provide as a feature.

Submitted, by the way: rust-lang/rust#87139.