Standardize some usages of "which" in docstrings

[drewm1980]

In US english, "that" is used in restrictive clauses in place of
"which", and often affects the meaning of sentences.

In UK english and many dialects, no distinction is
made.

While Rust devs want to avoid unproductive pedanticism, it is worth at
least being uniform in documentation such as:

http://doc.rust-lang.org/std/iter/index.html

and also in cases where correct usage of US english clarifies the
sentence.

[flaper87]

Not a native english speaker but the PR looks good to me! Thanks for your contribution 👍

[drewm1980]

Thanks FlaPer87!

My reading of the contributor guide is that editing non-example parts of docstrings does not require re-running the test suite, but is a bit vague.

I have not build rust yet myself, let alone the test suite; I'm on a crappy laptop and no access to a workstation at the moment.

[drewm1980]

Oh hey, Travis is happy. Does that mean the tests passed too?

[steveklabnik]

Adding some citations, from http://www.chicagomanualofstyle.org/qanda/data/faq/topics/Whichvs.That.html :

The basic rule: Use “which” plus commas to set off nonrestrictive (unnecessary) clauses; use “that” to introduce a restrictive (necessary) clause:

Some people use “which” restrictively, which is more or less okay (and popular among writers of British English) as long as no commas are involved:

None of these examples have commas, so I'm inclined to say that they're okay. Then again, the CMOS isn't neccesarily authoritative, and both sound perfectly fine to my ear.

What do you think, @drewm1980 ?

[steveklabnik]

Also: Travis just runs a very simple formatting check, so it doesn't mean that all the tests pass, just that nothing is obviously wrong. Also, it's true, re-running the tests for just English changes isn't particularly important, our CI system will end up running them anyway, but this shouldn't change anything about them, so you don't need to as well.

[drewm1980]

@steveklabnik :

"In polished American prose, that is used restrictively to narrow a category or identify a particular item being talked about: “any building that is taller must be outside the state”; which is used nonrestrictively—not to narrow a class or identify a particular item but to add something about an item already identified: “alongside the officer trotted a toy poodle, which is hardly a typical police dog.”CMOS

The CMOS blog post you linked to is advocating ~not using the commas with "that", and using them with "which", in ~addition to using the precise American usage. Using which in these cases, with or without a comma sounds totally wrong to me, but I may be biased, having grown up in a suburb of Chicago rather than a suburb of London.

Anyway, the American usage is consistent with the Brittish rules, so at least in this case, we can be consistent AND support both US and British English. Besides, in this particular case we want user's eyes to be drawn to the differences between the iterators, not the differences between different dialects of English.

[steveklabnik]

Using which in these cases, with or without a comma sounds totally wrong to me, but I may be biased, having grown up in a suburb of Chicago rather than a suburb of London.

Oh, don't I know this feel. My hometown basically has an entire dialect: http://www.pittsburghese.com/

in this particular case we want user's eyes to be drawn to the differences between the iterators, not the differences between different dialects of English.

Agreed 100%.