Tracking issue for `#[doc(cfg(...))]` #43781
Comments
There are different implementations and signatures for `get_pollfd` depending on whether the target plateform is unix or windows. When generating the doc, we need both implementations to appear regardless of the target platform. This commit is inspired by the way Rust `std` library deals with `process::Command` OS dependent variants (https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt). Documentation can't be accurate though as we can't use the`std::os::windows` on `unix` and vice versa. As a workaround a fake fd class matching the other platform is declared. This could be further enhanced once `#[doc(cfg(...))]` is stabilized (rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]` or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported on **Windows/Unix** only`. Unfortunately, these comments disappear when generating will `--all-features` because they are not part of the documentation in the gir file.
There are different implementations and signatures for `get_pollfd` depending on whether the target platform is unix or windows. When generating the doc, we need both implementations to appear regardless of the target platform. This commit is inspired by the way Rust `std` library deals with `process::Command` OS dependent variants (https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt). Documentation can't be accurate though as we can't use the`std::os::windows` on `unix` and vice versa. As a workaround a fake fd class matching the other platform is declared. This could be further enhanced once `#[doc(cfg(...))]` is stabilized (rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]` or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported on **Windows/Unix** only`. Unfortunately, these comments disappear when generating will `--all-features` because they are not part of the documentation in the gir file.
There are different implementations and signatures for `get_pollfd` depending on whether the target platform is unix or windows. When generating the doc, we need both implementations to appear regardless of the target platform. This commit is inspired by the way Rust `std` library deals with `process::Command` OS dependent variants (https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt). Documentation can't be accurate though as we can't use the`std::os::windows` on `unix` and vice versa. As a workaround a fake fd class matching the other platform is declared. This could be further enhanced once `#[doc(cfg(...))]` is stabilized (rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]` or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported on **Windows/Unix** only`. Unfortunately, these comments disappear when generating will `--all-features` because they are not part of the documentation in the gir file.
There are different implementations and signatures for `get_pollfd` depending on whether the target platform is unix or windows. When generating the doc, we need both implementations to appear regardless of the target platform. This commit is inspired by the way Rust `std` library deals with `process::Command` OS dependent variants (https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt). Documentation can't be accurate though as we can't use the`std::os::windows` on `unix` and vice versa. As a workaround a fake fd class matching the other platform is declared. This could be further enhanced once `#[doc(cfg(...))]` is stabilized (rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]` or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported on **Windows/Unix** only`. Unfortunately, these comments disappear when generating will `--all-features` because they are not part of the documentation in the gir file.
There are different implementations and signatures for `get_pollfd` depending on whether the target platform is unix or windows. When generating the doc, we need both implementations to appear regardless of the target platform. This commit is inspired by the way Rust `std` library deals with `process::Command` OS dependent variants (https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt). Documentation can't be accurate though as we can't use the`std::os::windows` on `unix` and vice versa. As a workaround a fake fd class matching the other platform is declared. This could be further enhanced once `#[doc(cfg(...))]` is stabilized (rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]` or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported on **Windows/Unix** only`. Unfortunately, these comments disappear when generating will `--all-features` because they are not part of the documentation in the gir file.
There are different implementations and signatures for `get_pollfd` depending on whether the target platform is unix or windows. When generating the doc, we need both implementations to appear regardless of the target platform. This commit is inspired by the way Rust `std` library deals with `process::Command` OS dependent variants (https://doc.rust-lang.org/std/process/struct.Command.html#impl-CommandExt). Documentation can't be accurate though as we can't use the`std::os::windows` on `unix` and vice versa. As a workaround a fake fd class matching the other platform is declared. This could be further enhanced once `#[doc(cfg(...))]` is stabilized (rust-lang/rust#43781) by declaring `#[doc(cfg(unix))]` or `#[doc(cfg(windows))]` instead of the hard coded comments `This is supported on **Windows/Unix** only`. Unfortunately, these comments disappear when generating will `--all-features` because they are not part of the documentation in the gir file.
|
|
|
I think that |
|
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:
|
|
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. |
…c, r=QuietMisdreavus Stabilize cfg(doc) cc rust-lang#43781.
|
We tried out this feature in Syn (dtolnay/syn#734) and decided against using it yet. What I am happy withI 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 withOur 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.
|
|
The links in the opening post have gone dead. |
…=GuillaumeGomez Improve rendering of crate features via doc(cfg) The current rendering of crate features with `doc(cfg(feature = ".."))` is verbose and unwieldy for users, `doc(cfg(target_feature = ".."))` is special-cased to make it render nicely, and a similar rendering can be applied to `doc(cfg(feature))` to make it easier for users to read. I also added special casing of `all`/`any` cfgs consisting of just `feature`/`target-feature` to remove the repetitive "target/crate feature" prefix. The downside of this current rendering is that there is no distinction between `feature` and `target_feature` in the shorthand display. IMO this is ok, or if anything `target_feature` should have a more verbose shorthand, because `doc(cfg(feature = ".."))` usage is going to vastly outstrip `doc(cfg(target_feature = ".."))` usage in non-stdlib crates when it eventually stabilizes (or even before that given the number of crates using `cfg_attr(docsrs)` like constructs). ## Previously <img width="259" alt="Screenshot 2020-08-09 at 13 32 42" src="https://user-images.githubusercontent.com/81079/89731110-d090c000-da44-11ea-96fa-56adc6339123.png"> <img width="438" alt="image" src="https://user-images.githubusercontent.com/81079/89731116-d7b7ce00-da44-11ea-87c6-022d192d6eca.png"> <img width="765" alt="image" src="https://user-images.githubusercontent.com/81079/89731152-24030e00-da45-11ea-9552-1c270bff2729.png"> <img width="671" alt="image" src="https://user-images.githubusercontent.com/81079/89731158-28c7c200-da45-11ea-8acb-97d8a4ce00eb.png"> ## Now <img width="216" alt="image" src="https://user-images.githubusercontent.com/81079/89731123-e1d9cc80-da44-11ea-82a8-5900bd9448a5.png"> <img width="433" alt="image" src="https://user-images.githubusercontent.com/81079/89731127-e8684400-da44-11ea-9d18-572fd810f19f.png"> <img width="606" alt="image" src="https://user-images.githubusercontent.com/81079/89731162-2feed000-da45-11ea-98d2-8a88c364d903.png"> <img width="669" alt="image" src="https://user-images.githubusercontent.com/81079/89731991-ccb46c00-da4b-11ea-9416-cd20a3193826.png"> cc rust-lang#43781
|
What's the status of this? I've been using it on the time crate for as long as I can remember, and a number of other crates have been doing so as well. |
|
For searchability: this is feature |
|
I changed the rendering of Other than those changes, there are bugs around trait implementation handling such as #68100, I want to try and create an exhaustive test covering trait implementations once #77672 is done and fix their handling. After that, I feel like this would be ready for stabilization, it's had quite thorough usage on docs.rs already, so when rendering is all fixed we can rebuild the documentation for some large crates like |
|
I'm wondering: Would it not make sense to generate So the following #[cfg(all(target_feature = "avx", target_feature = "avx2"))]
#[doc(cfg(all(target_feature = "avx", target_feature = "avx2")))]
pub mod avx;could just be #[cfg(all(target_feature = "avx", target_feature = "avx2"))]
pub mod avx;Otherwise, we're duplicating information unnecessarily, right? |
|
...pretty much |
|
In the general case yes, but there are quite a few crates using things like internal |
|
What about the opposite - having |
|
Not sure how hard that would be to implement, though - maybe @petrochenkov would know? |
Simplify doc-cfg rendering based on the current context For sub-items on a page don't show cfg that has already been rendered on a parent item. At its simplest this means not showing anything that is shown in the portability message at the top of the page, but also for things like fields of an enum variant if that variant itself is cfg-gated then don't repeat those cfg on each field of the variant. This does not touch trait implementation rendering, as that is more complex and there are existing issues around how it deals with doc-cfg that need to be fixed first. ### Screenshots, left is current, right is new:      cc rust-lang#43781
Simplify doc-cfg rendering based on the current context For sub-items on a page don't show cfg that has already been rendered on a parent item. At its simplest this means not showing anything that is shown in the portability message at the top of the page, but also for things like fields of an enum variant if that variant itself is cfg-gated then don't repeat those cfg on each field of the variant. This does not touch trait implementation rendering, as that is more complex and there are existing issues around how it deals with doc-cfg that need to be fixed first. ### Screenshots, left is current, right is new:      cc rust-lang#43781
…GuillaumeGomez Add tests and improve rendering of cfgs on traits Shows the additional features required to get the trait implementation, suppressing any already shown on the current page. One interesting effect from this is if you have a cfg-ed type, implementing a cfg-ed trait (so the implementation depends on both cfgs), you will get the inverted pair of cfgs shown on each page:   The hidden items on the trait implementation also now get the correct cfgs displayed on them. Tests are blocked on rust-lang#78673. fixes rust-lang#68100 cc rust-lang#43781
…GuillaumeGomez Add tests and improve rendering of cfgs on traits Shows the additional features required to get the trait implementation, suppressing any already shown on the current page. One interesting effect from this is if you have a cfg-ed type, implementing a cfg-ed trait (so the implementation depends on both cfgs), you will get the inverted pair of cfgs shown on each page:   The hidden items on the trait implementation also now get the correct cfgs displayed on them. Tests are blocked on rust-lang#78673. fixes rust-lang#68100 cc rust-lang#43781
Issue with that is if you want to implement the same function on different platforms in different ways. It shouldn't show up as gated on the current platform, but as not gated at all... or if it's only implemented on a set of platforms, then as that list. So if there is such an implication, it should be opt in, eg via an empty
IMO it's strange if |
|
This is mostly looking good for syn. Filed one bug regarding the rendering of doc cfg on impls of empty traits: #79279. |
|
One situation where it would be nice to have doc_cfg but doesn't currently seem to be feasible is on derive-generated implementations. Even if the provider of the derive wanted to, they'd have to manually accept an equivalent attribute to doc_cfg, only to pass it on. Not something worth holding up stabilization over, but just something I noticed when adding in more attributes in some of my code. |
This is a tracking issue for the
#[doc(cfg(...))]attribute introduced in #43348.Steps:
(cc #1998)
The text was updated successfully, but these errors were encountered: