Compile fail stable #43949

GuillaumeGomez · 2017-08-17T20:14:17Z

Since #30726, we never made the compile_fail flag nor the error code check stable. I think it's time to change this fact.

r? @alexcrichton

Gankra · 2017-08-17T20:20:00Z

I'm a big fan of having "this doesn't compile" on stable, but as per our historical gripes with compile-fail tests, I'm not sure if we should allow stable code to check error codes, since I'm like 99.9% sure those aren't stable (in that something may stop compiling for a different reason).

GuillaumeGomez · 2017-08-17T20:37:01Z

If there is a consensus for not stabilizing the error code check, I'll just remove the second commit.

alexcrichton · 2017-08-17T22:19:21Z

Has this been discussed for stabilization? Was this discussed with @rust-lang/dev-tools?

I would personally still be against stabilizing error codes, and do we have sufficient documentation to stabilize this feature as well?

kennytm · 2017-08-17T22:29:00Z

cc #42288 for documentation (https://github.com/rust-lang/rust/blob/master/src/doc/rustdoc/src/documentation-tests.md)

GuillaumeGomez · 2017-08-22T11:49:29Z

Ok so I removed the error codes from the stabilization and added the doc for the compile_fail directive (and improved the doc a bit too).

alexcrichton · 2017-08-22T14:30:18Z

Are there any tests for this in the src/test/rustdoc folder? I'd expect that if we had existing tests this'd remove the feature gates from those tests.

alexcrichton · 2017-08-22T14:30:47Z

I'll I'm going to defer to @nrc for review as I think the dev-tools team will want to sign off on this.

r? @nrc

GuillaumeGomez · 2017-08-22T20:12:50Z

The tests are literally all over the docs. Where would you want me to add them?

alexcrichton · 2017-08-22T21:51:39Z

Can you add a unit test for this in src/test/rustdoc to ensure that it doesn't require a feature gate?

GuillaumeGomez · 2017-08-23T07:53:30Z

Sure.

frewsxcv · 2017-08-23T18:57:42Z

src/doc/rustdoc/src/documentation-tests.md

+   ```text
+   /// Some documentation.
+   # fn foo() {}
+   ```


why did these get indented?

To be able to see the backticks when rendered.

But that's not the point. The point is to show what happens when you hide a line with #, not to highlight the text differently.

also it caused a travis failure:

[01:04:47] ---- /checkout/src/doc/rustdoc/src/documentation-tests.md - Documentation_tests (line 68) stdout ---- [01:04:47] error: unknown start of token: `

nrc · 2017-08-24T06:36:35Z

I don't think we can yet get an auto-rfc-bot thing for the dev-tools/docs team, so manually. I propose we should accept this (stabilise the flag) - seems like a fairly harmless feature that has not changed in the last 1.5 years and is considered useful by some people.

Please sign off - @michaelwoerister @killercup @QuietMisdreavus @steveklabnik @jonathandturner @japaric

QuietMisdreavus · 2017-08-24T14:18:05Z

I approve this change.

In the docs team meeting yesterday, we mentioned that it might be prudent to include a note in the documentation stating that "this code doesn't compile" isn't guaranteed to be stable from release to release. Language features like NLL, struct field init shorthand, using a nightly feature without a feature flag (if it's stabilized as-is), etc, can make code that was previously broken start compiling. Making it explicit that some things may change between releases would be helpful in terms of cutting down on "where is this documented" questions.

GuillaumeGomez · 2017-09-01T20:12:39Z

I think I made the changes you required @QuietMisdreavus. Or did I miss anything?

QuietMisdreavus · 2017-09-02T14:51:49Z

src/doc/rustdoc/src/documentation-tests.md

@@ -136,7 +149,7 @@ explanation.
 Another case where the use of `#` is handy is when you want to ignore
 error handling. Lets say you want the following,

-```rust,ignore
+```rust


Note that taking the ignore off of this keeps making the test fail, because it's a doc comment that doesn't document anything.

Erf, good point!

QuietMisdreavus · 2017-09-02T14:52:24Z

src/doc/rustdoc/src/documentation-tests.md

@@ -233,6 +246,16 @@ not actually pass as a test.
 # fn foo() {}
 ```

+`compile_fail` tells `rustdoc` that the compilation should fail. If it
+compiles, then the test will fail.


Still looking for a note here about how things may start compiling in later releases.

QuietMisdreavus · 2017-09-02T14:53:54Z

src/doc/rustdoc/src/documentation-tests.md

@@ -16,6 +16,19 @@ The basic idea is this:
 The triple backticks start and end code blocks. If this were in a file named `foo.rs`,
 running `rustdoc --test foo.rs` will extract this example, and then run it as a test.

+Please note that by default, if no language is set for the block code, `rustdoc`
+assumes it is `Rust` code. So the following:


This block doesn't seem related to the rest of this PR? Like, it's worth noting, but it's not part of "making compile_fail stable".

Do you want me to put this change in another commit?

QuietMisdreavus · 2017-09-02T20:15:59Z

src/doc/rustdoc/src/documentation-tests.md

@@ -233,6 +246,17 @@ not actually pass as a test.
 # fn foo() {}
 ```

+`compile_fail` tells `rustdoc` that the compilation should fail. If it
+compiles, then the test will fail. However please note that a code
+failing with the current rustc version may works in a future release.


Light phrasing nit: "However please note that code failing with the current Rust release may work in a future release, as new features are added."

QuietMisdreavus

More travis failures

QuietMisdreavus · 2017-09-02T21:57:21Z

src/doc/rustdoc/src/documentation-tests.md

+
+    ```rust
+    let x = 5;
+    ```


Don't indent these docblocks. It's treating the ``` as part of the doctest and failing to parse it.

QuietMisdreavus · 2017-09-02T21:58:31Z

src/doc/rustdoc/src/documentation-tests.md

+/// let x = 5;
+/// x += 2; // shouldn't compile!
+/// ```
+```


"Documentation comment that doesn't document anything"

Probably good to stick ignore on this one.

GuillaumeGomez · 2017-09-03T14:25:43Z

Finally all good!

GuillaumeGomez · 2017-09-10T12:12:09Z

Any news in here?

carols10cents · 2017-09-11T15:25:13Z

ping the @rust-lang/dev-tools team for signoffs; here's some manual ticky boxes for you:

killercup · 2017-09-14T18:00:01Z

Assuming all the stuff from #43949 (comment) is addressed (it appears so), LGTM.

@CAROLBOT reviewed

michaelwoerister · 2017-09-14T19:57:56Z

@rfcbot reviewed

alexcrichton · 2017-09-14T22:59:19Z

@bors: r+

bors · 2017-09-14T22:59:21Z

📌 Commit ebc195d has been approved by alexcrichton

bors · 2017-09-15T08:05:46Z

⌛ Testing commit ebc195d with merge fd4bef5...

@alexcrichton

…hton Compile fail stable Since #30726, we never made the `compile_fail` flag nor the error code check stable. I think it's time to change this fact. r? @alexcrichton

bors · 2017-09-15T11:40:33Z

☀️ Test successful - status-appveyor, status-travis
Approved by: alexcrichton
Pushing fd4bef5 to master...

rust-highfive assigned alexcrichton Aug 17, 2017

GuillaumeGomez force-pushed the compile_fail_stable branch from 1c52987 to a81681c Compare August 17, 2017 20:15

GuillaumeGomez mentioned this pull request Aug 17, 2017

Add a cfail mode for doc comments #24565

Closed

GuillaumeGomez force-pushed the compile_fail_stable branch from a81681c to a52176f Compare August 22, 2017 11:48

rust-highfive assigned nrc and unassigned alexcrichton Aug 22, 2017

arielb1 added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Aug 22, 2017

frewsxcv reviewed Aug 23, 2017

View reviewed changes

steveklabnik mentioned this pull request Aug 23, 2017

Add dev-tools peer groups to rfcbot rust-lang/rfcbot-rs#153

Closed

nrc added T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. I-nominated labels Aug 24, 2017

carols10cents added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Aug 28, 2017

arielb1 added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Aug 29, 2017

frewsxcv mentioned this pull request Sep 1, 2017

Document compile_fail for doc tests #42288

Closed

set compile_fail flag stable

ccc31ce

GuillaumeGomez force-pushed the compile_fail_stable branch from a52176f to e8da3e1 Compare September 1, 2017 20:10

GuillaumeGomez force-pushed the compile_fail_stable branch from e8da3e1 to 56fb9ef Compare September 2, 2017 14:23

QuietMisdreavus reviewed Sep 2, 2017

View reviewed changes

GuillaumeGomez force-pushed the compile_fail_stable branch 2 times, most recently from a2f7aa5 to 82c04af Compare September 2, 2017 20:03

QuietMisdreavus reviewed Sep 2, 2017

View reviewed changes

GuillaumeGomez force-pushed the compile_fail_stable branch from 82c04af to a6ab711 Compare September 2, 2017 20:38

QuietMisdreavus reviewed Sep 2, 2017

View reviewed changes

GuillaumeGomez added 2 commits September 3, 2017 13:15

Add compile_fail documentation

2ffcfeb

Add precision for rustdoc block codes

ebc195d

GuillaumeGomez force-pushed the compile_fail_stable branch from a6ab711 to ebc195d Compare September 3, 2017 11:15

QuietMisdreavus mentioned this pull request Sep 7, 2017

Codeblock color #44397

Merged

bors merged commit ebc195d into rust-lang:master Sep 15, 2017

GuillaumeGomez deleted the compile_fail_stable branch September 15, 2017 12:56

alexcrichton added the relnotes Marks issues that should be documented in the release notes of the next release. label Sep 15, 2017

QuietMisdreavus mentioned this pull request Sep 21, 2017

Deprecate several flags in rustdoc #44138

Merged

apiraino removed the S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). label May 25, 2023

Compile fail stable #43949

Compile fail stable #43949

Conversation

GuillaumeGomez commented Aug 17, 2017 • edited Loading

Gankra commented Aug 17, 2017

GuillaumeGomez commented Aug 17, 2017

alexcrichton commented Aug 17, 2017

kennytm commented Aug 17, 2017 • edited Loading

GuillaumeGomez commented Aug 22, 2017

alexcrichton commented Aug 22, 2017

alexcrichton commented Aug 22, 2017

GuillaumeGomez commented Aug 22, 2017

alexcrichton commented Aug 22, 2017

GuillaumeGomez commented Aug 23, 2017

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

nrc commented Aug 24, 2017

QuietMisdreavus commented Aug 24, 2017

GuillaumeGomez commented Sep 1, 2017

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

GuillaumeGomez commented Sep 3, 2017

GuillaumeGomez commented Sep 10, 2017

carols10cents commented Sep 11, 2017 • edited by nrc Loading

killercup commented Sep 14, 2017

michaelwoerister commented Sep 14, 2017

alexcrichton commented Sep 14, 2017

bors commented Sep 14, 2017

bors commented Sep 15, 2017

bors commented Sep 15, 2017

GuillaumeGomez commented Aug 17, 2017 •

edited

Loading

kennytm commented Aug 17, 2017 •

edited

Loading

carols10cents commented Sep 11, 2017 •

edited by nrc

Loading