[lib] Harmonize punctuation of 'Effects: Equivalent to' #1815
Conversation
|
Thanks -- but all editorial changes are frozen until the motions are in. I think we'll get new cases like this coming in, so I will ask you to recheck at that point. |
|
See #1806 for a competing pull request. |
source/iostreams.tex
Outdated
| @@ -12823,7 +12823,7 @@ | |||
|
|
|||
| \begin{itemdescr} | |||
| \pnum | |||
| \effects Equivalent to \tcode{pathobject = p}, | |||
| \effects Equivalent to: \tcode{pathobject = p}, | |||
There was a problem hiding this comment.
Do we want colons here? What follows is an expression, not a statement, non?
There was a problem hiding this comment.
No, it's not just the expression: all of what follows is part of the "Equivalent to". It seemed prudent to add the colon to highlight that fact.
There was a problem hiding this comment.
Hm, I thought it reads nicer without the colon, like a normal sentence. @zygoloid, a native speaker's opinion?
There was a problem hiding this comment.
Why do we add the colon for the "statement" case, then? I thought because "something big" was coming along.
There was a problem hiding this comment.
I always thought it was because of the grammatical nature of what follows: the colon separates sentences, or "statements", if you will. If you just have an expression, it's naturally an object of the current sentence.
There was a problem hiding this comment.
(I'm happy to merge everything except these two, which I'd like discussed further.)
There was a problem hiding this comment.
I've dropped these two contentious changes.
source/strings.tex
Outdated
| @@ -2449,7 +2425,7 @@ | |||
|
|
|||
| \begin{itemdescr} | |||
| \pnum | |||
| \effects Equivalent to \tcode{insert(pos, basic_string(n, c))}. | |||
| \effects Equivalent to: \tcode{return insert(pos, basic_string(n, c));} | |||
There was a problem hiding this comment.
Now the \returns below is redundant.
source/utilities.tex
Outdated
|
|
||
| \pnum\returns \tcode{*this}. | ||
| \pnum\effects Equivalent to: | ||
| \tcode{shared_ptr(r).swap(*this); return *this;} | ||
|
|
There was a problem hiding this comment.
We lost the \returns here?
There was a problem hiding this comment.
No. Look at the end of line 9443; there's a second statement, which happens to be a return statement.
There was a problem hiding this comment.
Oh eek. Can we make that a codeblock then?
There was a problem hiding this comment.
Or keep the \returns, maybe?
There was a problem hiding this comment.
Yes. I'm not keen on getting overly creative in compressing stuff. Readability is important. The return *this = that; is borderline, too (but I was going to let it slide).
There was a problem hiding this comment.
I've undone the changes in this area.
source/utilities.tex
Outdated
| \pnum | ||
| \returns \tcode{*this}. | ||
| \effects Equivalent to: | ||
| \tcode{shared_ptr(std::move(r)).swap(*this); return *this;} |
|
Rebased + contentious change dropped. |
Fixes #1119.