New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Various cosmetic and minor changes #57016

Open
wants to merge 1 commit into
base: master
from

Conversation

@alexreg
Copy link
Contributor

alexreg commented Dec 20, 2018

r? @Centril :-D

@Centril

This comment has been minimized.

Copy link
Contributor

Centril commented Dec 20, 2018

For the purposes of review I'd prefer if you could:

  1. separate code changes from changes to comments into different PRs.
  2. separate various changes with done with regexes from each other into different PRs.

That's both easier to review and much easier to get through bors.

@rust-highfive

This comment was marked as outdated.

Copy link
Collaborator

rust-highfive commented Dec 20, 2018

The job x86_64-gnu-llvm-6.0 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.
travis_time:end:0464a560:start=1545332457594937489,finish=1545332461839140304,duration=4244202815
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
[00:24:09] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "build" "--target" "x86_64-unknown-linux-gnu" "-j" "4" "--release" "--locked" "--color" "always" "--features" "panic-unwind backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "--message-format" "json"
[00:24:09] expected success, got: exit code: 101
[00:24:09] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap build
[00:24:09] Build completed unsuccessfully in 0:20:52
[00:24:09] make: *** [all] Error 1
[00:24:09] Makefile:28: recipe for target 'all' failed

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)

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 20, 2018

@Centril sure, will do later.

@scalexm

This comment has been minimized.

Copy link
Member

scalexm commented Dec 20, 2018

Before provoking a lot of merge conflicts again, would it be possible for some other people of e.g., @rust-lang/docs @rust-lang/compiler to confirm that these kinds of PRs are wanted on a regular basis?

@@ -669,7 +669,7 @@ impl char {
}
}

/// Returns true if this `char` is alphanumeric, and false otherwise.
/// Returns whether this `char` is alphanumeric, and false otherwise.

This comment has been minimized.

@nikic

nikic Dec 20, 2018

Contributor

The "and false otherwise" part no longer makes sense if this construction is used. (Same applies to many other places.)

This comment has been minimized.

@GuillaumeGomez

GuillaumeGomez Dec 20, 2018

Member

I prefer true if but not being a native english speaker, not sure which is "better"...

This comment has been minimized.

@alexreg

alexreg Dec 20, 2018

Contributor

“Whether” is definitely better, as a native speaker. They’re both grammatically correct, but “whether” is more succinct and to the point. It’s like writing boolval as opposed to if boolval { true } else { false }, which is an anti-pattern by anyone’s measure.

This comment has been minimized.

@alexreg

alexreg Dec 20, 2018

Contributor

@nikic Good point, I'll remedy that. It's the problem with find-and-replace.

This comment has been minimized.

@steveklabnik

steveklabnik Dec 21, 2018

Member

I personally think true if is a bit better/easier. I don't find it more succinct; it's literally the same number of characters. Additionally, true if is something that's very direct for programmers, even if whether might make more sense outside of a programming context.

This comment has been minimized.

@Centril

Centril Dec 30, 2018

Contributor

Given my experience with English teachers (I was accepted to grad school in English), in my experience they're much less dogmatic than that.

What you call dogma I call respect for other people's time. Let's not fill this thread with anecdotes about our various formal-English-writing teachers, ye? I've had them too and they would care about this.

My view is that, we should aspire to the same standards academic papers have in at least the reference and imo also the standard library. The rustc code-base doesn't need the same level of rigor. We should however also not try to be intentionally casual when someone does the work, as @alexreg has, of improving writing style.

This comment has been minimized.

@steveklabnik

steveklabnik Dec 30, 2018

Member

I fundamentally do not believe this to be an improvement.

(The other changes? Very much so. This one? Not so much.)

This comment has been minimized.

@Centril

Centril Dec 30, 2018

Contributor

@steveklabnik Reasonable minds can disagree. :)

This comment has been minimized.

@petrochenkov

petrochenkov Dec 30, 2018

Contributor

“Whether” is definitely better, as a native speaker

I probably prefer true if exactly because I'm not a native speaker.
I probably can't even pronounce "whether" properly, and it took me years to discern it from "weather".
It's better for technical documentation to use some kind of simplified, a bit pseudocode-like version of English, to be clear for larger audience. There's a long history behind this general idea.

This comment has been minimized.

@alexreg

alexreg Jan 1, 2019

Contributor

@petrochenkov If you had to pronounce the word when reading documentation, you'd possibly have a good point... (it's pronounced exactly the same in most English dialects, but is almost always easy to distinguish from context). In any case, "whether" is definitely part of elementary English vocabulary, so I'm not sure how strong an argument it is for written English.

@steveklabnik While do I strongly feel this is an improvement (it's not a matter of dogma so much as expressivity or directness, to me), I am however happy to let this stand as a subjective point, and defer to your preference, if it helps get this PR merged. :-) I know the PR will be discussed by several people in the next lang team meeting though, so it presumably won't be a decision taken by one person, at least not up-front...

@nikomatsakis

This comment has been minimized.

Copy link
Contributor

nikomatsakis commented Dec 20, 2018

Regarding whether these sorts of changes are desirable, i'm of two minds. They are annoying when it comes to merge conflicts -- but on the other hand it is generally nice to have a codebase with typos fixed and things "cleaned up and consistent" (that said, I think some of these changes -- e.g., changing to "returns whether" from "returns true if" -- are not clearly better to me, just different).

I guess in general my attitude has been "hey, if somebody wants to make the changes and they seem neutral-to-good, why not".

Curious though to hear what others think.

One thing I definitely do prefer is to see the changes factored out into distinct commits (or, in this case, PRs).

@petrochenkov

This comment has been minimized.

Copy link
Contributor

petrochenkov commented Dec 20, 2018

-0.5 from me.
I'm ok with formatting changes like "two spaces" -> "one space" (they would better be done by rustfmt though) and with "variable_name" -> "variable_name".
But other changes either make things worse ("true if" -> "whether"), or longer ("vs" -> "versus", moving comments to separate lines), or weirder ("def-id" -> "def-ID"), or just randomly change things in accordance with some subjective rules that I can't infer.
Also, churn is bad in general, I want git blame to lead to people who actually wrote the code rather than formatting changes.

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 20, 2018

@scalexm You’re really trying to make life difficult for me, aren’t you haha? 😄 I’m only trying to improve the messy aspects of the codebase.... Anyway I’ll consult team members on this.

@scalexm

This comment has been minimized.

Copy link
Member

scalexm commented Dec 20, 2018

@alexreg No that isn’t my goal at all! It’s just that I am unsure this is wanted by everyone, so as part of this community, I’d like at least a few voices to support that kind of changes before moving forward. Of course if there is a general consensus I’ll have no further objections.

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 20, 2018

@scalexm Fair enough. I was only half serious anyway. It's certainly worth getting the opinion of the compiler team, whose opinions matter most here, followed by frequent contributors to the codebase like you or me. I know you're against it mainly, but let's keep weighing things up...

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 20, 2018

@petrochenkov

But other changes either make things worse ("true if" -> "whether"), or longer ("vs" -> "versus", moving comments to separate lines), or weirder ("def-id" -> "def-ID"), or just randomly change things in accordance with some subjective rules that I can't infer.

"Whether" is definitely better, for the reason I stated above. I think you'll either have to trust a native speaker on this (though I'm sure you could find some who dispute my view)... or we'll just agree to disagree. :-)

I don't think "ID" is weirder. "ID" is always capitalised in English, so why not here too, as part of a hyphenated word? The problem is, all rules of natural language are subjective to varying degrees. There's no black and white. My discussion started on the internals forum isn't going to make progress any time soon, if it does, so this is the next best thing in my view.

Also, churn is bad in general, I want git blame to lead to people who actually wrote the code rather than formatting changes.

I think the downside is greatly exaggerated. One can easily look beyond the last edit. The idea is that going forwards, people will hopefully start conforming to a style consensus, even before it gets formalised (if it ever does). I do realise it's marginally harder to look at the blame history of a line or file beyond a certain commit, but it's only marginally.

@nikomatsakis I basically agree with that. On the plus side, these sorts of large cosmetic PRs will be few and far-between, and the conflicts are a bit annoying, but not that bad (usually very easy and quick to fix in my experience). I guess it's half me feeling in some sort of "obsessive-compulsive" frame of mind that makes me do these things, but I also genuinely feel they contribute to the long-term health of the codebase. :-)

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Dec 21, 2018

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

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 52c8286 to 781bb9d Dec 21, 2018

@rust-highfive

This comment was marked as resolved.

Copy link
Collaborator

rust-highfive commented Dec 21, 2018

The job x86_64-gnu-llvm-6.0 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.
travis_time:end:21a7df5e:start=1545368610868652551,finish=1545368613711224017,duration=2842571466
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---

[00:02:52] travis_fold:start:tidy
travis_time:start:tidy
tidy check
[00:02:52] tidy error: /checkout/src/bootstrap/test.rs:1997: line longer than 100 chars
[00:02:53] tidy error: /checkout/src/libsyntax/parse/lexer/mod.rs:574: line longer than 100 chars
[00:02:53] tidy error: /checkout/src/tools/tidy/src/features.rs:351: line longer than 100 chars
[00:02:53] tidy error: /checkout/src/librustc/ty/query/job.rs:48: line longer than 100 chars
[00:02:54] some tidy checks failed
[00:02:54] 
[00:02:54] 
[00:02:54] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/tidy" "/checkout/src" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "--no-vendor" "--quiet"
[00:02:54] 
[00:02:54] 
[00:02:54] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test src/tools/tidy
[00:02:54] Build completed unsuccessfully in 0:00:46
[00:02:54] Build completed unsuccessfully in 0:00:46
[00:02:54] Makefile:79: recipe for target 'tidy' failed
[00:02:54] make: *** [tidy] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:00328433
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Fri Dec 21 05:06:36 UTC 2018
---
travis_time:end:032d15e2:start=1545368797340628518,finish=1545368797346757630,duration=6129112
travis_fold:end:after_failure.3
travis_fold:start:after_failure.4
travis_time:start:1f5b8161
$ ln -s . checkout && for CORE in obj/cores/core.*; do EXE=$(echo $CORE | sed 's|obj/cores/core\.[0-9]*\.!checkout!\(.*\)|\1|;y|!|/|'); if [ -f "$EXE" ]; then printf travis_fold":start:crashlog\n\033[31;1m%s\033[0m\n" "$CORE"; gdb --batch -q -c "$CORE" "$EXE" -iex 'set auto-load off' -iex 'dir src/' -iex 'set sysroot .' -ex bt -ex q; echo travis_fold":"end:crashlog; fi; done || true
travis_fold:end:after_failure.4
travis_fold:start:after_failure.5
travis_time:start:043f5a7a
travis_time:start:043f5a7a
$ cat ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers || true
cat: ./obj/build/x86_64-unknown-linux-gnu/native/asan/build/lib/asan/clang_rt.asan-dynamic-i386.vers: No such file or directory
travis_fold:end:after_failure.5
travis_fold:start:after_failure.6
travis_time:start:053b1be4
$ dmesg | grep -i kill

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)

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 781bb9d to e3802d6 Dec 21, 2018

@rust-highfive

This comment has been minimized.

Copy link
Collaborator

rust-highfive commented Dec 21, 2018

The job x86_64-gnu-llvm-6.0 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.
travis_time:end:0161cece:start=1545370749328916942,finish=1545370752255872052,duration=2926955110
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
[01:01:04] ..........................................ii........................................................ 3600/5192
[01:01:05] ............................................................i....................................... 3700/5192
[01:01:07] .................................................................................................... 3800/5192
[01:01:08] .................i.................................................................................. 3900/5192
[01:01:11] ........................F........................................................................... 4000/5192
[01:01:24] .................................................................................................... 4200/5192
[01:01:27] .................................................................................................... 4300/5192
[01:01:31] .......................................................i............................................ 4400/5192
[01:01:37] .................................................................................................... 4500/5192

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)

@Zoxc

This comment has been minimized.

Copy link
Contributor

Zoxc commented Dec 21, 2018

I generally want to avoid churn unless there is a clear non-subjective improvement.

For the changes in this PR, there are several things I disagree with:

  • The removal of github links. I really want to keep those as it's very clear what they refer to and they are easy to open with a click.
  • The use of backticks in comments. I think that just adds unnecessary noise.
  • Not capitalizing sentences in FIXME comments.
@bors

This comment has been minimized.

Copy link
Contributor

bors commented Dec 21, 2018

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

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 21, 2018

@Zoxc Let me offer some rationale.

  • The removal of github links. I really want to keep those as it's very clear what they refer to and they are easy to open with a click.

a) There was inconsistent use of "issue #xyz" vs. URLs, b) URLs are noisy in comments and make them harder to read

  • The use of backticks in comments. I think that just adds unnecessary noise.

It makes it very clear what is not part of the normal English sentence (not just code, but metavariables and other expressions), and what isn't. Seems you're in a minority here, but not sure.

  • Not capitalizing sentences in FIXME comments.

This is minor, of course. It's a standard grammatical rule not to follow a colon with capitalisation though.

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from e3802d6 to cf2c1e0 Dec 21, 2018

@nikic

This comment has been minimized.

Copy link
Contributor

nikic commented Dec 21, 2018

This is minor, of course. It's a standard grammatical rule not to follow a colon with capitalisation though.

Style guides sometimes (e.g. AP) distinguish whether the words after the colon are a dependent clause, and use capitalization if it isn't. In the case of TODO/FIXME, what follows will usually not be a dependent clause and thus should be capitalized. Sometimes a distinction is made based on whether the colon is followed by one or by more than one sentences (e.g. Chicago).

I don't particularly care either way, but I think it's important to acknowledge that these changes are ultimately based on your personal preference in the choice of a particular style guide, not on normative rules of the English language. And that makes it hard to agree on things, because people will have different personal preferences.

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 21, 2018

I don't particularly care either way, but I think it's important to acknowledge that these changes are ultimately based on your personal preference in the choice of a particular style guide, not on normative rules of the English language. And that makes it hard to agree on things, because people will have different personal preferences.

This may be an American English thing. In fact, I just looked it up, and apparently we Brits always use lower case after colons, but Americans often follow the rule you stated above.

@Centril

This comment has been minimized.

Copy link
Contributor

Centril commented Dec 21, 2018

I mostly agree with @nikomatsakis.

On a tangent, I think that a more serious problem and a barrier to entry is the huge size of some files and functions/methods in the rust repo. Having >= 7000 LOC files strikes me as unmaintainable / unreadable and might point to larger architectural problem around APIs that are hard to refactor (possibly due to having too much context / being too stateful). A more healthy size would be ~300-1000 LOC per file imo.

@rust-highfive

This comment was marked as outdated.

Copy link
Collaborator

rust-highfive commented Dec 21, 2018

The job x86_64-gnu-llvm-6.0 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.
travis_time:end:1de05380:start=1545408094994088324,finish=1545408098199588097,duration=3205499773
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
travis_time:start:test_debuginfo
Check compiletest suite=debuginfo mode=debuginfo-both (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:07:46] 
[01:07:46] running 118 tests
[01:08:11] .iiiii...i.....i..i...i..i.i..i.ii..i.....i..i....i..........iiii..........i...ii...i.......ii.i.i.i 100/118
[01:08:15] ......iii.i.....ii
[01:08:15] 
[01:08:15]  finished in 29.084
[01:08:15] travis_fold:end:test_debuginfo

---
travis_time:start:test_rustdoc
Check compiletest suite=rustdoc mode=rustdoc (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:13:22] 
[01:13:22] running 284 tests
[01:14:27] ..........................i...............F......................................................... 100/284
[01:16:08] ....................................................................................
[01:16:08] failures:
[01:16:08] 
[01:16:08] ---- [rustdoc] rustdoc/escape-deref-methods.rs stdout ----
[01:16:08] ---- [rustdoc] rustdoc/escape-deref-methods.rs stdout ----
[01:16:08] 
[01:16:08] error: htmldocck failed!
[01:16:08] status: exit code: 1
[01:16:08] command: "/usr/bin/python2.7" "/checkout/src/etc/htmldocck.py" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc/escape-deref-methods" "/checkout/src/test/rustdoc/escape-deref-methods.rs"
[01:16:08] ------------------------------------------
[01:16:08] 
[01:16:08] ------------------------------------------
[01:16:08] stderr:
[01:16:08] stderr:
[01:16:08] ------------------------------------------
[01:16:08] 40: @"-Crpath -O -Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--target-rustcflags" "-Crpath -O -Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--docck-python" "/usr/bin/python2.7" "--lldb-python" "/usr/bin/python2.7" "--gdb" "/usr/bin/gdb" "--quiet" "--llvm-version" "6.0.0\n" "--system-llvm" "--cc" "" "--cxx" "" "--cflags" "" "--llvm-components" "" "--llvm-cxxflags" "" "--adb-path" "adb" "--adb-test-dir" "/data/tmp/work" "--android-cross-path" "" "--color" "always"
[01:16:08] 
[01:16:08] 
[01:16:08] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:16:08] Build completed unsuccessfully in 0:19:20
[01:16:08] Build completed unsuccessfully in 0:19:20
[01:16:08] Makefile:58: recipe for target 'check' failed
[01:16:08] make: *** [check] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.
travis_time:start:07c52ee8
$ date && (curl -fs --head https://google.com | grep ^Date: | sed 's/Date: //g' || true)
Fri Dec 21 17:17:58 UTC 2018

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)

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Dec 22, 2018

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

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from cf2c1e0 to 989310b Dec 23, 2018

@rust-highfive

This comment was marked as outdated.

Copy link
Collaborator

rust-highfive commented Dec 23, 2018

The job x86_64-gnu-llvm-6.0 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.
travis_time:end:02428816:start=1545537723325581944,finish=1545537726490994844,duration=3165412900
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
travis_time:start:test_debuginfo
Check compiletest suite=debuginfo mode=debuginfo-both (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:07:17] 
[01:07:17] running 118 tests
[01:07:41] .iiiii...i.....i..i...i..i.i..i.ii..i.....i..i....i..........iiii..........i...ii...i.......ii.i.i.i 100/118
[01:07:45] ......iii.i.....ii
[01:07:45] 
[01:07:45]  finished in 28.067
[01:07:45] travis_fold:end:test_debuginfo

---
travis_time:start:test_rustdoc-ui
Check compiletest suite=rustdoc-ui mode=ui (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
[01:36:50] 
[01:36:50] running 12 tests
[01:36:56] .F...F......
[01:36:56] 
[01:36:56] ---- [ui] rustdoc-ui/deprecated-attrs.rs stdout ----
[01:36:56] diff of stderr:
[01:36:56] 
[01:36:56] 
[01:36:56] 1 warning: the `#![doc(no_default_passes)]` attribute is considered deprecated
[01:36:56] -    = warning: please see https://github.com/rust-lang/rust/issues/44136
[01:36:56] +    = warning: see <https://github.com/rust-lang/rust/issues/44136>
[01:36:56] +    = warning: see <https://github.com/rust-lang/rust/issues/44136>
[01:36:56] 4    = help: you may want to use `#![doc(document_private_items)]`
[01:36:56] 5 
[01:36:56] 6 warning: the `#![doc(passes = "...")]` attribute is considered deprecated
[01:36:56] 7    |
[01:36:56] -    = warning: please see https://github.com/rust-lang/rust/issues/44136
[01:36:56] +    = warning: see <https://github.com/rust-lang/rust/issues/44136>
[01:36:56] 9 
[01:36:56] 9 
[01:36:56] 10 
[01:36:56] 
[01:36:56] 
[01:36:56] The actual stderr differed from the expected stderr.
[01:36:56] Actual stderr saved to /checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/deprecated-attrs/deprecated-attrs.stderr
[01:36:56] To update references, rerun the tests and pass the `--bless` flag
[01:36:56] To only update this specific test, also pass `--test-args deprecated-attrs.rs`
[01:36:56] error: 1 errors occurred comparing output.
[01:36:56] status: exit code: 0
[01:36:56] status: exit code: 0
[01:36:56] command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "/checkout/src/test/rustdoc-ui/deprecated-attrs.rs" "--target=x86_64-unknown-linux-gnu" "--error-format" "json" "-Zui-testing" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/deprecated-attrs/a" "-Zunstable-options" "-Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/deprecated-attrs/auxiliary"
[01:36:56] ------------------------------------------
[01:36:56] 
[01:36:56] ------------------------------------------
[01:36:56] stderr:
[01:36:56] stderr:
[01:36:56] ------------------------------------------
[01:36:56] {"message":"the `#![doc(no_default_passes)]` attribute is considered deprecated","code":null,"level":"warning","spans":[],"children":[{"message":"see <https://github.com/rust-lang/rust/issues/44136>","code":null,"level":"warning","spans":[],"children":[],"rendered":null},{"message":"you may want to use `#![doc(document_private_items)]`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"warning: the `#![doc(no_default_passes)]` attribute is considered deprecated\n   |\n   = warning: see <https://github.com/rust-lang/rust/issues/44136>\n   = help: you may want to use `#![doc(document_private_items)]`\n\n"}
[01:36:56] {"message":"the `#![doc(passes = \"...\")]` attribute is considered deprecated","code":null,"level":"warning","spans":[],"children":[{"message":"see <https://github.com/rust-lang/rust/issues/44136>","code":null,"level":"warning","spans":[],"children":[],"rendered":null}],"rendered":"warning: the `#![doc(passes = \"...\")]` attribute is considered deprecated\n   |\n   = warning: see <https://github.com/rust-lang/rust/issues/44136>\n\n"}
[01:36:56] ------------------------------------------
[01:36:56] 
[01:36:56] thread '[ui] rustdoc-ui/deprecated-attrs.rs' panicked at 'explicit panic', src/tools/compiletest/src/runtest.rs:3259:9
[01:36:56] note: Run with `RUST_BACKTRACE=1` for a backtrace.
---
[01:36:56] 1 error: `[i]` cannot be resolved, ignoring it...
[01:36:56] -   --> $DIR/intra-link-span-ice-55723.rs:21:10
[01:36:56] +   --> $DIR/intra-link-span-ice-55723.rs:20:10
[01:36:56] 3    |
[01:36:56] 4 LL | /// (arr[i])
[01:36:56] 
[01:36:56] 
[01:36:56] The actual stderr differed from the expected stderr.
[01:36:56] Actual stderr saved to /checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/intra-link-span-ice-55723/intra-link-span-ice-55723.stderr
[01:36:56] Actual stderr saved to /checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/intra-link-span-ice-55723/intra-link-span-ice-55723.stderr
[01:36:56] To update references, rerun the tests and pass the `--bless` flag
[01:36:56] To only update this specific test, also pass `--test-args intra-link-span-ice-55723.rs`
[01:36:56] error: 1 errors occurred comparing output.
[01:36:56] status: exit code: 1
[01:36:56] status: exit code: 1
[01:36:56] command: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "/checkout/src/test/rustdoc-ui/intra-link-span-ice-55723.rs" "--target=x86_64-unknown-linux-gnu" "--error-format" "json" "-Zui-testing" "-o" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/intra-link-span-ice-55723/a" "-Zunstable-options" "-Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "-L" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui/intra-link-span-ice-55723/auxiliary"
[01:36:56] ------------------------------------------
[01:36:56] 
[01:36:56] ------------------------------------------
[01:36:56] stderr:
[01:36:56] stderr:
[01:36:56] ------------------------------------------
[01:36:56] {"message":"`[i]` cannot be resolved, ignoring it...","code":{"code":"intra_doc_link_resolution_failure","explanation":null},"level":"error","spans":[{"file_name":"/checkout/src/test/rustdoc-ui/intra-link-span-ice-55723.rs","byte_start":739,"byte_end":740,"line_start":20,"line_end":20,"column_start":10,"column_end":11,"is_primary":true,"text":[{"text":"/// (arr[i])","highlight_start":10,"highlight_end":11}],"label":"cannot be resolved, ignoring","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"lint level defined here","code":null,"level":"note","spans":[{"file_name":"/checkout/src/test/rustdoc-ui/intra-link-span-ice-55723.rs","byte_start":506,"byte_end":539,"line_start":13,"line_end":13,"column_start":9,"column_end":42,"is_primary":true,"text":[{"text":"#![deny(intra_doc_link_resolution_failure)]","highlight_start":9,"highlight_end":42}],"label":null,"suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[],"rendered":null},{"message":"to escape `[` and `]` characters, just add '\\' before them like `\\[` or `\\]`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"error: `[i]` cannot be resolved, ignoring it...\n  --> /checkout/src/test/rustdoc-ui/intra-link-span-ice-55723.rs:20:10\n   |\nLL | /// (arr[i])\n   |           ^ cannot be resolved, ignoring\n   |\nnote: lint level defined here\n  --> /checkout/src/test/rustdoc-ui/intra-link-span-ice-55723.rs:13:9\n   |\nLL | #![deny(intra_doc_link_resolution_failure)]\n   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n   = help: to escape `[` and `]` characters, just add '\\' before them like `\\[` or `\\]`\n\n"}
[01:36:56] ------------------------------------------
[01:36:56] 
[01:36:56] thread '[ui] rustdoc-ui/intra-link-span-ice-55723.rs' panicked at 'explicit panic', src/tools/compiletest/src/runtest.rs:3259:9
[01:36:56] 
---
[01:36:56] test result: FAILED. 10 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out
[01:36:56] 
[01:36:56] 
[01:36:56] 
[01:36:56] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/compiletest" "--compile-lib-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib" "--run-lib-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "--rustc-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustc" "--rustdoc-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustdoc" "--src-base" "/checkout/src/test/rustdoc-ui" "--build-base" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/rustdoc-ui" "--stage-id" "stage2-x86_64-unknown-linux-gnu" "--mode" "ui" "--target" "x86_64-unknown-linux-gnu" "--host" "x86_64-unknown-linux-gnu" "--llvm-filecheck" "/usr/lib/llvm-6.0/bin/FileCheck" "--host-rustcflags" "-Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--target-rustcflags" "-Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--docck-python" "/usr/bin/python2.7" "--lldb-python" "/usr/bin/python2.7" "--gdb" "/usr/bin/gdb" "--quiet" "--llvm-version" "6.0.0\n" "--system-llvm" "--cc" "" "--cxx" "" "--cflags" "" "--llvm-components" "" "--llvm-cxxflags" "" "--adb-path" "adb" "--adb-test-dir" "/data/tmp/work" "--android-cross-path" "" "--color" "always"
[01:36:56] 
[01:36:56] 
[01:36:56] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:36:56] Build completed unsuccessfully in 0:40:39
[01:36:56] Build completed unsuccessfully in 0:40:39
[01:36:56] Makefile:58: recipe for target 'check' failed
[01:36:56] make: *** [check] Error 1
The command "stamp sh -x -c "$RUN_SCRIPT"" exited with 2.

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)

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 989310b to 7535bcb Dec 23, 2018

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 7535bcb to f23a15b Dec 23, 2018

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Dec 24, 2018

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

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from f23a15b to 0e26a62 Dec 25, 2018

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Dec 26, 2018

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

@nikomatsakis

This comment has been minimized.

Copy link
Contributor

nikomatsakis commented Dec 28, 2018

In general, I would be careful @alexreg in declaring anything to be "objectively" better, particularly when it comes to English, which is certainly an unruly language lacking any kind of "centralized" authority (I can't say if the same is true for other languages). =)

Definitely things like whether to capitalize after a colon have a variety of rules (amusingly, this exact question came up recently for me as I was trying to edit some of my daughter's homework, and couldn't predict what rules the teacher might be using).

My personal take is that I prefer backticks in comments to identify variable names and the like and don't really care about the rest. e.g., a URL is fine, but it's also ok to write #2123, as long as I can easily find the thing in question.

As for the fate of this PR, I'm not yet sure what to do exactly. As I wrote before, I don't object to merging it. I do however have reservations about trying to standardize rules on this sort of thing -- I'm not eager to be nitpicking PRs on random grammatical rules like whether to capitalize a sentence fragment after the word "whether". (Note: Here I am referring specifically to internal comments -- public-facing documentation is another thing.)

One thing I did notice is that this PR edits both internal rustc APIs as well as the documentation for things in libstd. It does strike me as reasonable to have a "style guide" for the latter, but I would expect @rust-lang/docs to be involved in developing it. It might be wise to separate out those changes, ultimately, not sure.

For the time being, I've nominated the PR for discussion at a @rust-lang/compiler meeting.

@steveklabnik

This comment has been minimized.

Copy link
Member

steveklabnik commented Dec 28, 2018

@nikomatsakis

This comment has been minimized.

Copy link
Contributor

nikomatsakis commented Dec 28, 2018

The docs team has two merged RFCs related to style for public comments, incidentally.

Yes, but I don't recall whether they addressed these specific questions.

@@ -1388,7 +1388,7 @@ impl String {
self.vec.len()
}

/// Returns `true` if this `String` has a length of zero.
/// Returns whether this `String` has a length of zero.

This comment has been minimized.

@nikomatsakis

nikomatsakis Dec 28, 2018

Contributor

Example of a change affecting public-facing documentation. That feels to me like a @rust-lang/docs decision.

This comment has been minimized.

@alexreg

alexreg Dec 29, 2018

Contributor

Fair point. The quality of public-facing documentation in rustc currently isn't great (at least compared to the stdlib and some libraries), but it would be nice if it reaches that level some day, and if the style is consistent with the stdlib.

@alexreg

This comment has been minimized.

Copy link
Contributor

alexreg commented Dec 28, 2018

Thanks for the nomination @nikomatsakis. English does lack a central authority, as you say (Spanish and French notably have one, I believe). That said, there are certain things that are for all intents and purposes objective, and others that are more subjective or dialectal – they all fall on a spectrum though.

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 0e26a62 to 5f3868c Dec 29, 2018

@rust-highfive

This comment was marked as resolved.

Copy link
Collaborator

rust-highfive commented Dec 29, 2018

The job x86_64-gnu-llvm-6.0 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.
travis_time:end:02dbeed8:start=1546062113175955925,finish=1546062116308034417,duration=3132078492
$ git checkout -qf FETCH_HEAD
travis_fold:end:git.checkout

Encrypted environment variables have been removed for security reasons.
See https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions
$ export SCCACHE_BUCKET=rust-lang-ci-sccache2
$ export SCCACHE_REGION=us-west-1
Setting environment variables from .travis.yml
$ export IMAGE=x86_64-gnu-llvm-6.0
---
[01:02:07] ...................................................ii............................................... 3600/5202
[01:02:09] ......................................................................i............................. 3700/5202
[01:02:10] .................................................................................................... 3800/5202
[01:02:12] .........................i.......................................................................... 3900/5202
[01:02:15] .................................F.................................................................. 4000/5202
[01:02:28] .................................................................................................... 4200/5202
[01:02:31] .................................................................................................... 4300/5202
[01:02:35] .................................................................i.................................. 4400/5202
[01:02:41] .................................................................................................... 4500/5202
---
[01:03:03] 
[01:03:03] thread 'main' panicked at 'Some tests failed', src/tools/compiletest/src/main.rs:495:22
[01:03:03] 
[01:03:03] 
[01:03:03] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/compiletest" "--compile-lib-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib" "--run-lib-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/lib/rustlib/x86_64-unknown-linux-gnu/lib" "--rustc-path" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage2/bin/rustc" "--src-base" "/checkout/src/test/ui" "--build-base" "/checkout/obj/build/x86_64-unknown-linux-gnu/test/ui" "--stage-id" "stage2-x86_64-unknown-linux-gnu" "--mode" "ui" "--target" "x86_64-unknown-linux-gnu" "--host" "x86_64-unknown-linux-gnu" "--llvm-filecheck" "/usr/lib/llvm-6.0/bin/FileCheck" "--host-rustcflags" "-Crpath -O -Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--target-rustcflags" "-Crpath -O -Zunstable-options  -Lnative=/checkout/obj/build/x86_64-unknown-linux-gnu/native/rust-test-helpers" "--docck-python" "/usr/bin/python2.7" "--lldb-python" "/usr/bin/python2.7" "--gdb" "/usr/bin/gdb" "--quiet" "--llvm-version" "6.0.0\n" "--system-llvm" "--cc" "" "--cxx" "" "--cflags" "" "--llvm-components"

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)

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 5f3868c to 8de50e7 Dec 29, 2018

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Dec 29, 2018

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

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 8de50e7 to 2e9d1c2 Dec 31, 2018

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Jan 1, 2019

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

@alexreg alexreg force-pushed the alexreg:cosmetic-2 branch from 2e9d1c2 to 6434aaf Jan 1, 2019

@bors

This comment has been minimized.

Copy link
Contributor

bors commented Jan 1, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment