-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features #3631
base: master
Are you sure you want to change the base?
Conversation
Co-authored-by: León Orell Valerian Liehr <me@fmease.dev> Co-authored-by: Michael Howell <michael@notriddle.com>
text/000-rustdoc-cfgs-handling.md
Outdated
|
||
### `#[doc(auto_cfg)]`/`#[doc(no_auto_cfg)]` | ||
|
||
By default, `#[doc(auto_cfg)]` is enabled at the crate-level. When it's enabled, Rustdoc will automatically display `cfg(...)` compatibility information as-if the same `#[doc(cfg(...))]` had been specified. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we want to change this default in existing code, or maybe this should be edition tied?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As far as I can see, it doesn't bring downside to have more information displayed by default, so I think it shouldn't be tied to an edition.
text/000-rustdoc-cfgs-handling.md
Outdated
|
||
In some situations, the detailed conditional compilation rules used to implement the feature might not serve as good documentation (for example, the list of supported platforms might be very long, and it might be better to document them in one place). To turn it off, add the `#[doc(no_auto_cfg)]` attribute. | ||
|
||
Both `#[doc(auto_cfg)]` and `#[doc(no_auto_cfg)]` attributes impact all there descendants. You can then enable/disable them by using the opposite attribute on a given item. They can be used as follows: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The current implementation only allows these attributes at the crate-level, has there been a push to support this arbitrary nesting from somewhere?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(Well, actually the attributes don't exist, feature(doc_auto_cfg)
implies default-active doc(auto_cfg)
, but IIRC previous discussions about how to expose a stable toggle had only considered adding in the attribute toggling it at the crate-level).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The current implementation only allows these attributes at the crate-level, has there been a push to support this arbitrary nesting from somewhere?
No, it's a change brought by this RFC: users will be able to use them on items directly if they want to have better control where they want it to be enabled or not.
Just like lints, I think it's better to give better control over this. For example if someone wants to completely override doc cfg attributes on a given item, they will be able to disable it for this item completely and then add what they want using doc(cfg())
. For this I'm thinking mostly about if you have "parent" features with a lot of children and for some reasons you have a complex cfg
to handle it and want to simplify its display when rendered in documentation.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
#[doc(cfg(...))]
already overrides #[cfg(...)]
on a single item, you don't need to disable the auto-cfg for that.
The use case where you would want to disable doc(auto_cfg)
on a sub-tree seems to be if you have a lot of cfg
on sub-items of that tree that you don't want rendered at all (but these cfg
aren't ones you want to globally #[doc(cfg_hide(...))]
), and so by disabling it you get to avoid putting #[doc(cfg())]
on each sub-item individually. But that seems like an unlikely situation to me.
Similarly wanting to #[cfg_hide(...)]
some cfg
within just a sub-tree seems very unlikely,
Making these attributes work within the module tree brings in extra complexity by requiring the inverses to exist. If they're restricted to applying only at the crate root we only need two new attributes: #[doc(no_auto_cfg)]
(assuming the default is active) and #[doc(cfg_hide(...))]
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair point. I'll limit doc(auto_cfg)
as a crate-level attribute.
For cfg_hide
I'm less convinced as you might want to hide some cfgs only for some modules/items (this is very hypothetical though). As for the complexity, it seems pretty low in a visitor: we add new entries before iterating to the children and remove them once we leave the current item (but that's just an implementation detail, not sure it's something that we should take into account here).
Anyway, if no one seems to be interested into having cfg_show
/cfg_hide
to be used on a specific module/item, then I will turn them into crate-level attribute (well, cfg_show
would be useless in this case so it'll be simply removed).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I just thought about a use case where having doc(auto_cfg)
not only as a crate-level attribute would be a nice improvement! In sysinfo, I disabled the doc_auto_cfg
because every item is available, whatever the OS (even unsupported ones). Except that I recently splitted the components to enable them through features. So I can either do:
#![doc(auto_cfg = true)]
#![doc(cfg_hide(/* list of all supported OSes */)]
Or instead disable auto_cfg
at the crate level and enable it on the components module directly without needing to worry about hiding cfg
s since the OS information handling is one level upper.
So with this in mind, I think we should lift the crate-level only restriction on auto_cfg
. What do you think?
#![doc(cfg_hide(doc))] | ||
``` | ||
|
||
Or directly on a given item/module as it covers any of the item's descendants: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Again the current implementation only supports being set at the crate-level, are there usecases that want to be able to limit it to certain sub-trees?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The one case I'm thinking about is to reduce complexity of rendered doc cfg as described in this comment.
I'm in favour of this but I would recommend clarifying the |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Was any thought given to what I mentioned in the draft RFC? Correctly annotating re-exports from a different crate is something that would be very useful for façade crates and similar, and is the sole blocker for refactoring time
to be split along more sensible lines. That would reduce code duplication a significant amount.
text/000-rustdoc-cfgs-handling.md
Outdated
|
||
When this is turned on, `#[cfg]` attributes are shown in documentation just like `#[doc(cfg)]` attributes are. | ||
|
||
* `#[doc(cfg_hide(...))]` / `#[doc(cfg_show(...))]` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
issue: so i've never been happy with the sheer number of different doc options this feature introduces: the names are kind of all over the place and hard to predict.
I think #[doc(cfg(..))]
is fine, but it would be nice if the rest all derived from each other.
Perhaps #[doc(auto_cfg(disable))]
, #[doc(auto_cfg(show(...), hide(...))]
etc? Ideally we only introduced one new doc attribute but I'm not sure if that's easy since cfg
can accept anything. Potentially could use the distinction between cfg(..)
and cfg = ...
here. Thoughts?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I personally wouldn't like using cfg = ...
since it would just make the distinction more confusing. I'm not really sure there's a massive benefit to having doc(auto_cfg(show(...)))
versus doc(cfg_show(...))
since, while it is literally combining two attributes into one, it just feels like unnecessary extra typing to me.
That said, perhaps there would be a case for having doc(auto_cfg(...))
for doc(cfg_show(...))
and doc(auto_cfg(not(...)))
for doc(cfg_hide(...))
, since it would fit in with existing cfg
and be a bit more discoverable. Perhaps doc(auto_cfg(all))
and doc(auto_cfg(none))
could be allowed as aliases for enabling/disabling all options.
Still has some issues, but, if we were to change the existing attributes, I'd prefer something like that over just combining the show
and hide
into a single auto_cfg
attribute.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@clarfonthey point taken on subtle syntax, I didn't really want to propose that anyway which is why I proposed it coming out of auto_cfg
To me the main distinction between cfg_show
and auto_cfg(show)
is the latter is easier to remember: there are many potential names for cfg_show
and I won't remember which one it is. Especially since auto_cfg
has cfg
as the second word. It's inconsistent and confusing.
If everything trees out of a single attribute it's easier to remember IMO, and not confusing.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And yes I'm happy with experimentation with auto_cfg
, I didn't want to propose one particular solution there just want it to be something straightforward, intuitive, and easy to remember.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not exactly convinced that auto_cfg(show(...))
is easier to remember compared to cfg_show(...)
, and in both cases, IDEs can offer suggestions after typing doc(cfg
to let you know what's available.
My main point here is that having "fewer attributes" isn't really a principle we should be guided by, since what matters most is the user writing the code, not the compiler parsing it. To a user, auto_cfg(show(...))
and auto_cfg(hide(...))
are still two attributes; they just require extra parentheses compared to cfg_show(...)
and cfg_hide(...)
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Another option could be #[doc(auto_cfg_hide(...))]
then.
Though, I'm now wondering whether there's a way to change the semantics slightly so that cfg_hide
can take over the role of no_auto_cfg
too. Instead of disabling auto_cfg
completely just tell it to hide everything so it doesn't actually do anything. (Combined with my discussion above of restricting this to the crate-root that means there would only be two new attributes required in this RFC: #[doc(cfg(...))]
anywhere and #![doc(cfg_hide(...))]
at the root).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand what you suggested @Nemo157. Do you mean that if no argument is provided to cfg_hide
, it means that we hide everything?
So to summarize the discussion, it seems that we tend to for show
and hide
:
#[doc(cfg_show(test))]
#[doc(cfg_hide(test))]
As for enabling/disabling the feature, what do you think about:
#[doc(cfg_auto(enable)]
#[doc(cfg_auto(disable)]
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My understanding of the issue, after completely misunderstanding for a while (apologies, @Manishearth) is that the cfg_show
and cfg_hide
attributes make no reference to auto_cfg
and so it's not clear that they control automatically showing and hiding cfg
attributes. Manish' proposal of auto_cfg(show(...))
and auto_cfg(hide(...))
is one way of accomplishing this, but auto_cfg_show
and auto_cfg_hide
attributes could also accomplish this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't understand what you suggested @Nemo157. Do you mean that if no argument is provided to
cfg_hide
, it means that we hide everything?
I don't have a concrete syntax proposal, I just wanted to seed the idea in case someone else has thoughts on how it could be accomplished. Being able to reduce this feature to introducing a total of two attributes instead of five I think is a helpful simplification.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@clarfonthey yes, thanks. my two main complaints are that the split of attributes starting and ending with cfg is confusing (and the potential for them to do either makes it harder to remember even if we pick consistent names¹), and the second one is the one you describe: it's not clear that show/hide is about auto stuff.
¹ basically, even if we picked cfg_auto, cfg_show, cfg_hide, I am somewhat (but less) worried people will forget which way things are.
Applied first round of review comments. Thanks everyone! |
The end goal being to provide this information automatically so that the documentation maintenance cost won't increase. | ||
|
||
|
||
# Guide-level explanation |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I mentioned this as a regular comment, but I'll move it to a review so it gets noticed: I think that the guide-level explanation should clarify the cfg(any(doc, ...))
trick for making auto_cfg
work properly, since it's not immediately clear otherwise. Basically, conditional compilation is still applied before rustdoc runs, meaning you have to ensure that rustdoc can see code to document it. Then, because auto_cfg
by default ignores cfg(doc)
, only the other cfg
s are documented.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It was not ignored. You can see the RFC mentioning this here. If it's not clear enough, how would you word it?
…tribute not limited to crate-level
… about not being able to be used at crate-level
Updated the syntax for Removed restriction on |
I have re-read the reference part again, but I still don't understand why there are so many attributes.
It looks like having just |
A couple more questions.
|
Because future possibilities include to make this attribute work not only at crate-level but also on any item. And based on this discussion, I think it'll part of this RFC.
I have to admit I didn't think about cfg_hide(any(windows, not(unix))) How do we interpret the
It is not. As mentioned in the RFC:
Because they both fill different role. You might want to add your own "doc cfg" information to either override what
The RFC says:
So the semantics are covered I think. The RFC didn't make it clear it works with and without
I think I see why you mention it. I suppose you talk a case like:
In this case, since the |
… crate-level only restriction
So only remains the question: #[cfg(windows)]
mod module {
#![doc(cfg_hide(windows))]
fn item() {}
} How to allow #[cfg(windows)]
#[doc(cfg(windows)] // Will be displayed all the time
#[doc(cfg_hide(windows))] // Hides `windows` from `doc(auto_cfg)` rendering on `module` and its children
pub mod module {
#[cfg(windows)] // Not displayed because of `cfg_hide(windows)`!
pub fn item() {}
} So I'd be willing to not change anything in this regard. |
Just wanted to make sure that my comment above (#3631 (review)) wasn't missed, as there has been no response or acknowledgement 🙂 |
I don't understand your comments. Do you have an example of what you would want to do? |
For an overly simplified case, see https://github.com/jhpratt/doc-cfg-demo Running This situation is quite common with façade crates and is the sole reason I have not migrated large amounts of code from |
Okay so if I understand correctly what you say, reexported items should only show |
Effectively, yes. My point of view is "what does a consumer of the library care about". That would mean showing them what feature they need to enable such that the item is present, taking into account feature transitivity, etc. |
I added an example but normally it was covered. For the current case, this is a bug that should be solved. |
I think with this all questions/comments were answered/resolved? |
As long as we agree on intended behavior, and it seems we do, then I'm satisfied. As I'd said above, the behavior had changed since I originally checked; it previously had no annotation. Feel free to use that example as a rustdoc test whenever that gets fixed, by the way. No credit necessary. |
I definitely plan to. :3 |
I think it's time to start the FCP then. @rfcbot fcp merge |
Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members: No concerns currently listed. Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up! See this document for info about what commands tagged team members can give me. |
Friendly ping @Manishearth, @Nemo157, @aDotInTheVoid, @camelid, @jsha, this is blocking progress on stabilizing |
I don't think my old concern that I'm not going to block the RFC on that, but I don't want to approve it myself. If everyone else is fine with it that's fine, but I would like to see if the overall api surface can be made easier to remember. |
This RFC aims at providing rustdoc users the possibility to add visual markers to the rendered documentation to know under which conditions an item is available (currently possible through the following unstable features: `doc_cfg`, `doc_auto_cfg` and `doc_cfg_hide`). | ||
|
||
It does not aim to allow having a same item with different `cfg`s to appear more than once in the generated documentation. | ||
|
||
It does not aim to document items which are *inactive* under the current configuration (i.e., “`cfg`'ed out”). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
...I'm slightly confused by this preamble, honestly, because I would figure the most important time to know when something is available is when it is, in fact, not available... when it has been "cfg'd out" but can be enabled by other means.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You are right, this sentence doesn't tell the full story and should be improved (however, it's technically correct). I'm pretty sure the RFC does elaborate on it further down in the document (Ctrl+F doc
(Match Case, Match Full Words)).
It implicitly refers to rust-lang/rust#1998.
As you can probably guess, rustdoc doesn't and won't magically recompile the to-be-documented crate under all possible cfgs and combinations thereof to gather the information necessary to display the "portability info box".
So for the following crate, function
wouldn't show up in the generated docs unless you actually passed --cfg special
to rustdoc
:
#![feature(doc_auto_cfg)] // (A)
// #![feature(doc_cfg)] // (B)
// #[doc(cfg(special))] (B)
#[cfg(special)]
pub fn function() {}
Therefore, the common and offical workaround is the use of the semi-special cfg doc
:
#![feature(doc_auto_cfg)] // (A)
// #![feature(doc_cfg)] // (B)
// #[doc(cfg(special))] (B)
#[cfg(any(doc, special))]
pub fn function() {}
This gets more hairy if there are "multiple" functions called function
(where the cfg specs differ for obvious reasons), one needs to choose which of the many functions to annotate with doc
.
Of course, this doesn't scale to more complicated cases. E.g., if the parameter/return types differ by cfg spec. So, yeah. The general problem isn't solved. That's what I meant with the sentence you highlighted.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I mean, I've certainly written documentation that needs that invocation (or similar) to work properly. I guess I'm just feeling a bit perplexed that there is seemingly quite a lot of new concepts in this RFC and that's left unsolved. I would expect an RFC that has the sense of adding a Lot Of Stuff to also have an answer to that critical missing piece, because it's a right pain in the ass! ...or I would expect it to be smaller and more tightly scoped.
I realize that's a Pure Vibes thing, but I do think it can be a bit hard to evaluate a solution... and thus people would come to consensus slower... if it feels incorrectly scoped.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
rustdoc doesn't and won't magically recompile the to-be-documented crate under all possible cfgs and combinations thereof
i mean, rustc now tracks enough information that it doesn’t have to
rust-lang/rust#109005
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i mean, rustc now tracks enough information that it doesn’t have to
Well, rustc only stores the name of cfg'ed out items but rustdoc would need to have access to so much more (struct fields, function signatures, ...). See StrippedCfgItem
.
Edit: And doing that would drastically increase size of the crate metadata / rustc's memory use.
tracking issue
cc @rust-lang/rustdoc
Rendered