RFC for doc_cfg, doc_cfg_auto, doc_cfg_hide and doc_cfg_show features

[GuillaumeGomez]

tracking issue

cc @rust-lang/rustdoc

Rendered

[Nemo157]

Do we want to change this default in existing code, or maybe this should be edition tied?

[GuillaumeGomez]

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.

[Nemo157]

The current implementation only allows these attributes at the crate-level, has there been a push to support this arbitrary nesting from somewhere?

[Nemo157]

(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).

[GuillaumeGomez]

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.

[Nemo157]

#[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(...))].

[GuillaumeGomez]

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).

[GuillaumeGomez]

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 cfgs 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?

[Nemo157]

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?

[GuillaumeGomez]

The one case I'm thinking about is to reduce complexity of rendered doc cfg as described in this comment.

[clarfonthey]

I'm in favour of this but I would recommend clarifying the #[cfg(any(doc, ...))] trick in the guide-level explanation a bit further, since folks reading it might be misled into thinking that rustdoc will just ignore conditional compilation entirely to report things, which isn't true; it just shows the conditions when they're met.

[jhpratt]

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.

[Manishearth]

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?

[clarfonthey]

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.

[Manishearth]

@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.

[Manishearth]

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.

[clarfonthey]

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(...).

[GuillaumeGomez]

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)]

?

[clarfonthey]

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.

[Nemo157]

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.

[Manishearth]

@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.

[GuillaumeGomez]

So to summarize the current attributes this RFC proposes:

• doc(auto_cfg = true)/doc(auto_cfg = false) to enable/disable the auto_cfg feature
• doc(cfg(...)) to add a new cfg item in the rendered documentation
• doc(cfg_hide(...))/doc(cfg_show(...)) to (un)prevent a cfg to be rendered in the docs

It's 4 new attributes. If I understood what @Manishearth suggested, they'd like to instead go with:

doc(auto_cfg(hide(...)) instead of doc(cfg_hide(...)). It doesn't reduce the number of new attributes but it makes it more coherent in my opinion.

Did I miss something else you suggested @Manishearth ?

[GuillaumeGomez]

Applied first round of review comments. Thanks everyone!

[clarfonthey]

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 cfgs are documented.

[GuillaumeGomez]

It was not ignored. You can see the RFC mentioning this here. If it's not clear enough, how would you word it?

[GuillaumeGomez]

Updated the syntax for auto_cfg to instead accept true or false.

Removed restriction on doc(cfg()) which was marked as not being able to be used as a crate-level attribute as it currently works using it as such, so doesn't seem there is a good enough reason to change this behaviour.

[petrochenkov]

I have re-read the reference part again, but I still don't understand why there are so many attributes.

• Why is #![doc(auto_cfg = true)] necessary if it is the default?
• Why is #![doc(auto_cfg = false)] necessary if it is equivalent to #![doc(cfg_hide(any()))]?
  • If it is not equivalent, then why it needs to do something different? It would be better if they were equivalent and auto_cfg didn't need to exist.
• Why is #![doc(cfg_show(...))] necessary if it is equivalent to #![doc(cfg(...))]?
  • If it is not equivalent, then why it needs to do something different? It would be better if they were equivalent and cfg_show didn't need to exist.

It looks like having just doc(cfg) and doc(cfg_hide) would be enough to both explicitly enable and disable whatever configs are necessary, with cfg acting as a default.

[petrochenkov]

A couple more questions.

• Is #[doc(cfg)] currently allowed on an item without #[cfg]? What are the semantics?
  • I'd expect this to be allowed making cfg_show redundant as in the previous comment.
• Is it possible to show a cfg on an item, but hide it on all children of that item? (Without putting attributes on all those children individually.)

[GuillaumeGomez]

I have re-read the reference part again, but I still don't understand why there are so many attributes.

• Why is #![doc(auto_cfg = true)] necessary if it is the default?

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.

• Why is #![doc(auto_cfg = false)] necessary if it is equivalent to #![doc(cfg_hide(any()))]?

cfg_hide doesn't work like cfg: it only accepts "items". However, the RFC is very unclear about it, so I'll add it in the RFC.

• If it is not equivalent, then why it needs to do something different? It would be better if they were equivalent and auto_cfg didn't need to exist.

I have to admit I didn't think about cfg_show and cfg_hide to work this way at all. I'm not sure it's a good idea though. For example, how should we handle this case:

cfg_hide(any(windows, not(unix)))

How do we interpret the not(unix)? As a whole or should it invert the "hide unix"? So for simplicity, that's why not, any and all are not supported in cfg_hide and cfg_show and why we have cfg_auto.

• Why is #![doc(cfg_show(...))] necessary if it is equivalent to #![doc(cfg(...))]?

It is not. As mentioned in the RFC:

It only applies to #[doc(auto_cfg = true)], not to #[doc(cfg(...))].

• If it is not equivalent, then why it needs to do something different? It would be better if they were equivalent and cfg_show didn't need to exist.

Because they both fill different role. You might want to add your own "doc cfg" information to either override what auto_doc_cfg generates or add your own information.

A couple more questions.

• Is #[doc(cfg)] currently allowed on an item without #[cfg]? What are the semantics?

The RFC says:

This attribute provides a standardized format to override #[cfg()] attributes to document conditionally available items.
...
This attribute has the same syntax as conditional compilation

So the semantics are covered I think. The RFC didn't make it clear it works with and without cfg on the item though, so I'll add a clarification.

• I'd expect this to be allowed making cfg_show redundant as in the previous comment.

• Is it possible to show a cfg on an item, but hide it on all children of that item? (Without putting attributes on all those children individually.)

I think I see why you mention it. I suppose you talk a case like:

#[cfg(windows)]
mod module {
    #![doc(cfg_hide(windows))]

    fn item() {}
}

In this case, since the doc(cfg_hide(windows)) is also an attribute of module, it should impact module. I think we should say that inner doc(cfg_hide) and doc(cfg_show) attributes don't impact the item if they are inner attributes.

[GuillaumeGomez]

So only remains the question:

#[cfg(windows)]
mod module {
    #![doc(cfg_hide(windows))]

    fn item() {}
}

How to allow cfg(windows) to be displayed on module while having it hidden on its children? I think what the RFC offer is good enough:

#[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.

[jhpratt]

Just wanted to make sure that my comment above (#3631 (review)) wasn't missed, as there has been no response or acknowledgement 🙂

[GuillaumeGomez]

I don't understand your comments. Do you have an example of what you would want to do?

[jhpratt]

For an overly simplified case, see https://github.com/jhpratt/doc-cfg-demo

Running cargo +nightly doc --all-features on alpha will incorrectly say that alpha::S::foo is "Available on crate feature foo-method only." I hadn't checked this in a while, but previously it would have no annotation whatsoever. Ideally, the feature resolver would be utilized to show the correct annotation — it relies on the feature beta-foo-method.

This situation is quite common with façade crates and is the sole reason I have not migrated large amounts of code from time to time-core. Were I to do this, I could remove ~1000 LOC (off the top of my head) from time-macros that is currently duplicated.

[GuillaumeGomez]

Okay so if I understand correctly what you say, reexported items should only show cfgs from the reexport's point of view (so to speak)? That sounds reasonable. Once you confirm it, I'll update the RFC.

[jhpratt]

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.

[GuillaumeGomez]

I added an example but normally it was covered. For the current case, this is a bug that should be solved.

[GuillaumeGomez]

I think with this all questions/comments were answered/resolved?

[jhpratt]

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.

[GuillaumeGomez]

I definitely plan to. :3

[GuillaumeGomez]

I think it's time to start the FCP then.

@rfcbot fcp merge

[rfcbot]

Team member @GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @fmease
• @jsha
• @notriddle

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.

[madsmtm]

Friendly ping @Manishearth, @Nemo157, @aDotInTheVoid, @camelid, @jsha, this is blocking progress on stabilizing #[doc(cfg(...))] etc.

[Manishearth]

I don't think my old concern that auto_cfg and cfg_show are confusing since they are new terms using cfg in different spots has been addressed.

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.

[workingjubilee]

...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.

[fmease]

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.

[workingjubilee]

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.

[jyn514]

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

[fmease]

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.

[GuillaumeGomez]

There actually wasn't an explanation about this in the RFC so I added one in the Unresolved questions section.

[GuillaumeGomez]

I applied suggestions from @Manishearth about the hide/show attributes: since they're only applied on the auto_cfg feature cfgs, it makes more sense to embed them in the auto_cfg attribute (imo).

I also added an explanation about why cfged out items are not included by rustdoc.

[Manishearth]

@GuillaumeGomez nice! Should the syntax for auto_cfg then be doc(auto_cfg) and doc(auto_cfg = false) (with = true being accepted but not the primary documented syntax)?

[GuillaumeGomez]

You mean for doc(auto_cfg) to be equivalent to doc(auto_cfg = true), making the = true optional?

[Manishearth]

@GuillaumeGomez yes, so basically this means:

• doc(auto_cfg) = auto on
• doc(auto_cfg(show(..)) = auto on, and show stuff
• doc(auto_cfg = false) = turn it off
• doc(auto_cfg = true) = auto on, but not the primary documented syntax

the idea is that this way we have consistency: if you mention auto_cfg it enables it, you don't have to explicitly put = true if you're using show and can use a single invocation.

[GuillaumeGomez]

Not a super big fan of the implicit but it also kinda makes sense. Does it also include doc(auto_cfg(hide(...)))? Following the logic "if auto_cfg without = is used, it's enabled", it'd mean that auto_cfg(hide) would also enable auto_cfg. I'm fine with it but just want to confirm with you before updating the RFC.

[Manishearth]

Yeah, hide doesn't make any sense without auto_cfg.

I mostly don't want to mix the = and the () syntax too much, and this way most normal users only use the () syntax

[Manishearth]

At the very least, doc(auto_cfg) should work. My whole thrust here is to make the syntax relatively uniform and memorable.

[GuillaumeGomez]

Ok, updating the RFC to reflect it then. 👍

[GuillaumeGomez]

Added the new syntax (allowing to have no argument in auto_cfg) and also the new behaviour for auto_cfg(hide(...)) and auto_cfg(show(...)).

Thanks for the ideas!