RFC 2008 non-exhaustive enums/structs: Rustdoc #51854

davidtwco · 2018-06-27T19:57:29Z

Part of #44109. Not sure how those who maintain rustdoc primarily would prefer this addition look or where it should be placed, happy to make any changes required.

r? @QuietMisdreavus (not sure if this is the right person, just guessing)

clarfonthey · 2018-06-27T20:34:59Z

Mind sharing a screenshot of what this looks like?

davidtwco · 2018-06-27T20:38:53Z

@clarcharr

I'm not sure it's perfect, but I'm more than happy to adjust it to something better.

rust-highfive · 2018-06-27T21:35:52Z

The job x86_64-gnu-llvm-3.9 of your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[01:23:24] travis_time:end:stage0-rustdoc-themes:start=1530135345900665780,finish=1530135347050704467,duration=1150038687

[01:23:24] rustdoc: [theme-checker] Starting tests!
[01:23:24]  - Checking "/checkout/src/librustdoc/html/static/themes/dark.css"... FAILED
[01:23:24]   Missing ".stab.non-exhaustive" rule
[01:23:24] 
[01:23:24] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/rustdoc-themes" "/checkout/obj/build/bootstrap/debug/rustdoc" "/checkout/src/librustdoc/html/static/themes"
[01:23:24] expected success, got: exit code: 1
[01:23:24] 
[01:23:24] 
[01:23:24] 
[01:23:24] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:23:24] Build completed unsuccessfully in 0:42:42
[01:23:24] make: *** [check] Error 1
[01:23:24] Makefile:58: recipe for target 'check' failed

The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:123a773c
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

clarfonthey · 2018-06-27T21:43:33Z

Ah, looks good! Although the message is a bit odd, and personally I'd recommend customising the message depending on whether it's a struct or enum.

I'm also a bit confused on the microscope icon, as I get the sentiment behind "a closer look" although it looks a bit off for me. Although without an icon it'd look worse, so, idk.

davidtwco · 2018-06-27T22:07:59Z

I've made it say what it is (struct, enum, etc.). I only included the microscope icon as that is (as far as I can tell) always included in the little boxes like that one.

I agree that the message is a bit off, I can't think of a better one at the moment (else I'd have included it) but if anyone reading this can think of one, I'll happily change it.

clarfonthey · 2018-06-27T22:28:50Z

What I thought of for enums: This enum is marked as non-exhaustive, and additional variants may be added in the future. When matching over values of this type, an extra _ arm must be added to account for future extensions.

However, for structs, I think that it might be better to do the opposite and only add a message if all of these things can be done normally. Something along the lines of "all of this struct's fields are public, and it can be constructed normally with the Struct { .. } syntax."

The RFC suggested using the /* fields omitted */ comment in the definition, although the latest rustdoc hides declarations. I'm filing a bug for this.

clarfonthey · 2018-06-27T22:33:06Z

(I edited that comment enough times I'm going to add a comment that I did so for people viewing the response via email)

QuietMisdreavus

cc @rust-lang/rustdoc for the implementation and @rust-lang/docs for the placement of the "non-exhaustive" disclaimer and its wording. I'm not totally sure what was agreed upon for how #[non_exhaustive] was supposed to be noted in docs, but i'd like to make sure there's some agreement in the docs team for how we do it.

QuietMisdreavus · 2018-07-05T19:50:13Z

src/librustdoc/clean/mod.rs

@@ -366,6 +368,7 @@ pub struct Item {
    pub def_id: DefId,
    pub stability: Option<Stability>,
    pub deprecation: Option<Deprecation>,
+    pub non_exhaustive: bool,


I think i'd prefer seeing the non_exhaustive marker just on the kinds where it's relevant, so just Struct/Enum/etc, instead of on Item here where literally everything has to care about it.

On the other hand, if i remember right we do keep all the ast::Attributes around in the Attributes struct, so we could just query them as needed, rather than passing this flag around all the way from clean_ast to html/render.

This should be resolved now.

QuietMisdreavus · 2018-07-05T19:55:16Z

src/librustdoc/html/render.rs

@@ -2194,6 +2194,7 @@ fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Re
        info!("Documenting {}", name);
    }
    document_stability(w, cx, item)?;
+    document_non_exhaustive(w, item)?;


...though now i see why you did it this way. I commented in #51860 (comment) that this marker could go into the "Fields" or "Variants" sections of the struct/enum pages, rather than at the top of the full docs.

davidtwco · 2018-07-12T19:14:59Z

@QuietMisdreavus @clarcharr I've updated this to move the message to the suggested location.

frewsxcv · 2018-07-13T03:37:12Z

src/librustdoc/clean/mod.rs

+    pub fn is_non_exhaustive(&self) -> bool {
+        self.attrs.other_attrs.iter()
+            .filter(|a| a.name().as_str() == "non_exhaustive")
+            .count() > 0


It may be more peformant to use .any() instead of .count() > 0

Fixed this.

davidtwco · 2018-07-17T20:06:16Z

@rust-lang/rustdoc @rust-lang/docs Would appreciate some feedback on whether the message and placement are appropriate so we can get this landed!

GuillaumeGomez · 2018-07-17T22:14:19Z

This is very confusing and it takes a lot of place. Not very convinced by the current add...

…psed by default and easier to understand.

davidtwco · 2018-07-18T19:30:22Z

I've updated the PR to hide the message by default and to update the wording slightly.

When collapsed:

When expanded:

Thoughts? @rust-lang/rustdoc @rust-lang/docs

GuillaumeGomez · 2018-07-19T07:47:01Z

With the message hidden by default, it's a bit better. However, why do we have a #[non_exhaustive] attribute?

davidtwco · 2018-07-19T09:01:46Z

@GuillaumeGomez #[non_exhaustive] was added in RFC 2008. In short, it requires that downstream crates add wildcard arms to any matches on structs/enums that are marked as #[non_exhaustive] so that new variants or fields being added to those types isn't a breaking change.

GuillaumeGomez · 2018-07-19T12:14:51Z

Ah I didn't know. Then no problem with it. If messages are hidden by default, then all good for me.

QuietMisdreavus · 2018-07-19T15:49:25Z

src/librustdoc/html/render.rs

+                       Therefore, non-exhaustive structs cannot be constructed in external crates \
+                       using the traditional <code>Struct {{ .. }}</code> syntax; cannot be \
+                       matched against without a wildcard <code>..</code>; and \
+                       functional-record-updates do not work.")?;


Is "functional-record-updates" a term we use elsewhere? I'm not familiar with what it could mean.

It seems like the book refers to it as struct update syntax, I'll change the PR to reflect this.

Pushed a commit that changes this.

The book actually didn't mention FRU at all so I was equally confused when the RFC came about. Struct update syntax is a much better way of putting it, and I'm glad it's finally in the book now.

QuietMisdreavus · 2018-07-19T15:51:11Z

This looks really nice! Thanks so much for working on this. I just have the one terminology question, but once that's done i'm ready to push the button on this!

QuietMisdreavus · 2018-07-19T18:31:27Z

Thanks for updating! Let's get this rolling!

@bors r+

bors · 2018-07-19T18:31:29Z

📌 Commit b671bdc has been approved by QuietMisdreavus

bors · 2018-07-19T19:03:11Z

⌛ Testing commit b671bdc with merge 11864c4...

@QuietMisdreavus

RFC 2008 non-exhaustive enums/structs: Rustdoc Part of #44109. Not sure how those who maintain rustdoc primarily would prefer this addition look or where it should be placed, happy to make any changes required. r? @QuietMisdreavus (not sure if this is the right person, just guessing)

bors · 2018-07-19T21:13:56Z

☀️ Test successful - status-appveyor, status-travis
Approved by: QuietMisdreavus
Pushing 11864c4 to master...

Display #[non_exhaustive] in rustdoc on types.

a074bd7

rust-highfive assigned QuietMisdreavus Jun 27, 2018

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jun 27, 2018

davidtwco mentioned this pull request Jun 27, 2018

Tracking issue for RFC 2008: Future-proofing enums/structs with #[non_exhaustive] attribute #44109

Closed

7 tasks

Include type in non-exhaustive message. Include new css in dark theme.

039709d

clarfonthey mentioned this pull request Jun 27, 2018

Hiding of struct declarations means constructability isn't really documented #51860

Closed

Improved non_exhaustive message.

3e59aef

QuietMisdreavus reviewed Jul 5, 2018

View reviewed changes

Simplified checking for non_exhaustive attribute.

5ccafa1

Moved non_exhaustive message to fields/variants section and onto type.

9527d6a

davidtwco force-pushed the rfc-2008-rustdoc branch from bfd2b55 to 9527d6a Compare July 12, 2018 19:22

frewsxcv reviewed Jul 13, 2018

View reviewed changes

Switch to any from count when checking for non_exhaustive attribute.

d0d33a0

Updated wording and placement of non-exhaustive notice so it is colla…

959a13d

…psed by default and easier to understand.

QuietMisdreavus reviewed Jul 19, 2018

View reviewed changes

Updated FRU terminology.

b671bdc

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). labels Jul 19, 2018

bors merged commit b671bdc into rust-lang:master Jul 19, 2018

davidtwco deleted the rfc-2008-rustdoc branch July 19, 2018 21:38

daurnimator mentioned this pull request May 20, 2019

non-exhaustive enums ziglang/zig#2524

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC 2008 non-exhaustive enums/structs: Rustdoc #51854

RFC 2008 non-exhaustive enums/structs: Rustdoc #51854

davidtwco commented Jun 27, 2018

clarfonthey commented Jun 27, 2018

davidtwco commented Jun 27, 2018

rust-highfive commented Jun 27, 2018

clarfonthey commented Jun 27, 2018

davidtwco commented Jun 27, 2018

clarfonthey commented Jun 27, 2018 •

edited

Loading

clarfonthey commented Jun 27, 2018

QuietMisdreavus left a comment

QuietMisdreavus Jul 5, 2018

davidtwco Jul 5, 2018

QuietMisdreavus Jul 5, 2018

davidtwco commented Jul 12, 2018

frewsxcv Jul 13, 2018 •

edited

Loading

davidtwco Jul 13, 2018

davidtwco commented Jul 17, 2018 •

edited

Loading

GuillaumeGomez commented Jul 17, 2018

davidtwco commented Jul 18, 2018

GuillaumeGomez commented Jul 19, 2018

davidtwco commented Jul 19, 2018

GuillaumeGomez commented Jul 19, 2018

QuietMisdreavus Jul 19, 2018

davidtwco Jul 19, 2018

davidtwco Jul 19, 2018

clarfonthey Jul 19, 2018

QuietMisdreavus commented Jul 19, 2018

QuietMisdreavus commented Jul 19, 2018

bors commented Jul 19, 2018

bors commented Jul 19, 2018

bors commented Jul 19, 2018

RFC 2008 non-exhaustive enums/structs: Rustdoc #51854

RFC 2008 non-exhaustive enums/structs: Rustdoc #51854

Conversation

davidtwco commented Jun 27, 2018

clarfonthey commented Jun 27, 2018

davidtwco commented Jun 27, 2018

rust-highfive commented Jun 27, 2018

clarfonthey commented Jun 27, 2018

davidtwco commented Jun 27, 2018

clarfonthey commented Jun 27, 2018 • edited Loading

clarfonthey commented Jun 27, 2018

QuietMisdreavus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidtwco commented Jul 12, 2018

frewsxcv Jul 13, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidtwco commented Jul 17, 2018 • edited Loading

GuillaumeGomez commented Jul 17, 2018

davidtwco commented Jul 18, 2018

GuillaumeGomez commented Jul 19, 2018

davidtwco commented Jul 19, 2018

GuillaumeGomez commented Jul 19, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuietMisdreavus commented Jul 19, 2018

QuietMisdreavus commented Jul 19, 2018

bors commented Jul 19, 2018

bors commented Jul 19, 2018

bors commented Jul 19, 2018

clarfonthey commented Jun 27, 2018 •

edited

Loading

frewsxcv Jul 13, 2018 •

edited

Loading

davidtwco commented Jul 17, 2018 •

edited

Loading