Highlight default enum variant in rustdoc output

[omid]

Problem

Since Rust has introduced #[default], can we hightlight it in the doc?
Like this one:

#[derive(Default)]
enum Status {
    #[default]
    Active,
    Inactive,
}

For other type of default definition of enums, it can be hard! For example, the following code, can be hard:

#[derive(...)]
enum Status {
    Active,
    Inactive,
}

impl Default for Status {
    fn default() -> Self {
        serde::from_str("active").unwrap()
    }
}

or:

#[derive(...)]
enum Status {
    Active,
    Inactive,
}

impl Default for Status {
    fn default() -> Self {
        if env!("ENV") == "prod" {
            Self::Inactive
        } else {
            Self::Active
        }
    }
}

We can ignore these cases.

Proposed Solution

No response

Notes

No response

[epage]

To double check, you are asking for changes in the documentation that cargo doc generates? If so, that would actually be with the underlying rustdoc tool and we can move this issue to the appropriate repo.

[omid]

Yes, thanks

[GuillaumeGomez]

What do you mean by highlighted?

[omid]

@GuillaumeGomez any way to show it or make it visible in docs. It can be shown as a flag in front of the default variant or whatever.

[fmease]

I'm not super convinced that there is any benefit in displaying #[default] at all in the docs. It's a niche feature and in most other cases (structs, variants with payloads), the crate author needs to keep documenting the default value of their type manually (if they choose to disclose it). All in all, is it worth adding extra code for this corner case?

What do y'all think?

[Nemo157]

It also feels like showing this attribute in the docs is similar to #90435, it surfaces something that might not be considered stable API by the author and implies that it is stable.

[Valentin271]

Just giving my opinion here.

From a crate maintainability point of view this would be great.

We use #[default] a lot in Ratatui.

Documenting every enum like below is kind of cumbersome, plus we have to keep it in sync with the actual attribute (which, granted, shouldn't be that often).

I feel like this is more of a robustness thing, where a comment can't be out of sync with the actual code (which matches the philosophy of compile checking doc-comment imo).

I also feel like this is a similar request as https://doc.rust-lang.org/rustdoc/unstable-features.html#extensions-to-the-doc-attribute.
I don't know the codebase at all so I could be completely wrong here, but treating #[default] seems like adding a condition somewhere to show a banner on the variant. Not a lot of extra code?

it surfaces something that might not be considered stable

I disagree, a default derive has the visibility of its enum, if the enum is public then it should be stable. As such, the default is documented only if the enum, and in tern default, are public.

---

Also, if this ever makes it https://rust-lang.github.io/rfcs/3107-derive-default-enum.html#overriding-default-fields, this request would make even more sense.

In the example, if beta is public and the default is 1, I want to know that as a lib user.
Of course if the field is private it shouldn't be documented and neither should its default.

---

Again this is just my opinion, I understand you guys have high stability constraints and all sort of other constraints :)

[Nemo157]

I disagree, a default derive has the visibility of its enum, if the enum is public then it should be stable. As such, the default is documented only if the enum, and in tern default, are public.

The fact that Default is implemented is public and must be stable, which exact value it returns might not be.