You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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?
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:
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.
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 :)
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.
Activity
kloenk commentedon Jul 12, 2021
I figured out that I can just enable it (in #439). But We should discuss if I'm allowed to use it :-)
ojeda commentedon Jul 14, 2021
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 thedoc(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:
and it looks very nice!
ojeda commentedon Jul 14, 2021
Actually, that gives me an idea:
rustdoccould 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, forCONFIG_NETwe could have the banner with:instead of:
(It looks worse here than in the generated docs).
nbdd0121 commentedon Jul 14, 2021
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_cfgeven it's gone from rustc, we can remove all usages easily, so I don't think it'll be problematic to use it.Sounds like something doable by some simple text postprocessing :)
ojeda commentedon Jul 14, 2021
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 :)
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.
rust: kernel: enable `doc_cfg` unstable feature
rust: kernel: enable `doc_cfg` unstable feature
remoteproc: core: Fix ida_free call while not allocated
btrfs: initialize inode mapping flags for cached inodes