Add a default flag for enum documentation

[omid]

fixes #115438

Disclaimer: It's my first PR, I don't know the regulation here yet 🙏🏼
I'm not sure if there are some styling standards, who's responsible for that and also I couldn't find tests for enum docs, for example if an enum is non_exhaustive or not.
I also don't know how I can test the code I've written, in general!

[rustbot]

Failed to set assignee to fmease: invalid assignee

Note: Only org members, users with write permissions, or people who have commented on the PR may be assigned.

[rustbot]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @fmease (or someone else) soon.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

• @rustbot author: the review is finished, PR author should check the comments and take action accordingly
• @rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

[fmease]

r? @fmease

[fmease]

Thanks for your PR! I have a couple of suggestions regarding the implementation.
However, I'm not sure if we want to pursue this feature at all as I've noted in the relevant issue.
Let's first hear what the others have to say over there in reply to my comment.

[fmease]

I also don't know how I can test the code I've written, in general!

If you mean you don't know how to manually test (i.e., run and check) the code, I can only recommend https://rustc-dev-guide.rust-lang.org (search for rustdoc and rustup toolchain link), you can then run rustdoc +stage2 input.rs (and similar).

If you would like to know how to write a test, check out the tests in tests/rustdoc/ as well as src/tools/htmldocck.py for a list of the syntax. I don't think we have a test file for attributes We do have tests/rustdoc/attributes.rs.

[fmease]

@rustbot label -S-waiting-on-review S-waiting-on-team

[GuillaumeGomez]

I'll add this to the rustdoc team meeting list to be discussed in next meeting.

EDIT: Mostly for the UI part.

[bors]

☔ The latest upstream changes (presumably #114855) made this pull request unmergeable. Please resolve the merge conflicts.

[fmease]

Sorry for the delay. The rustdoc team seems to be in favor of showing this information (Zulip). They're not in favor of showing #[default] in the source code snippet (.item-decl) but only at the variants' docs in the form of a “chip” (I assume they mean a colored box similar to the ones shown on unstable and deprecated items).

Could you rebase your PR, address my old review comments and adapt to the suggested format?

[omid]

@fmease to be on the same page... you mean something like the 👎🏼 section in the picture below:

But in the "Variants" area, like here:

[fmease]

Yes, exactly! Just to make sure: @Manishearth, is this ^ what you meant by “chip” on Zulip?

[omid]

Thanks, in this case, let's agree on the emoji and text also.

So far:
1.

2.

3.

or something else?
I think the 3rd one looks better.

[GuillaumeGomez]

I vote for 2 or 3.

[fmease]

Personally speaking I like option 3 the most :)

[Manishearth]

3 > 1 > 2 for me, strong preference for 3

[rfcbot]

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

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

Concerns:

• usefulness (Add a default flag for enum documentation #115575 (comment))

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.

[camelid]

@rfcbot concern usefulness

I think this is an interesting feature, but I'm concerned about its usefulness and its possibility of causing confusion. The chip only appears on variants that are marked with the relatively new #[default] attribute, and the attribute only supports fieldless variants. So it only appears in a small subset of cases. But then, if the author used a manual Default impl (either because they wrote the code before #[default], or because the default needs to have fields), it won't have a "Default" chip. IMO this could be confusing to (especially new) users, who see "Default" chips on some variants but not others, even though the others also have Default impls. They may not realize that enums that don't have the chip on them can (and often do) still have defaults on them.

[GuillaumeGomez]

Also an important note about getting the default enum variant from the Default trait impl: if the returned value depends on a static variable or anything that could return different values at different point of the program, it'd be impossible for rustdoc to get the correct value.

And finally, the #[default] currently seem to be able to be used on unit variants, limiting its usefulness even further.

[notriddle]

I used to weakly support this change, but after hearing camelid's argument, changed my mind and retracted my checkmark.

We don't need built-in support for stuff like this.

• In APIs that really do benefit from pointing out which variant the default is, the doc author can use their words and say /// This variant is returned by Default::default()`.
• Implementing Default is often bad API design. It should only be used if it's going to be obvious at the call site what it's going to return. Otherwise, the API should be designed with more specifically named functions.
  • We should use sugar like this to reward good design. Paradoxically, the better-designed the API is, the less useful the default badge would be. This feature rewards bad API design.

[fmease]

It seems like the majority of team members has changed their opinion towards closing this PR. So far, nobody has put forward any arguments against the concern (which agrees with my initial sentiment). fcp-close then?

[notriddle]

@rfcbot fcp cancel

@rfcbot fcp close

[rfcbot]

@notriddle proposal cancelled.

[rfcbot]

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

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @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.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

[GuillaumeGomez]

Closing then. Thanks again for bringing this to our attention @omid !