The proper use of 'e.g.' and 'i.e.' are confusing and reportedly are one of the most frequent sources of mistakes editors see in technical writing/documentation. Drupal's docblock and code documentation includes some examples of incorrect usage as well.
Let's start to correct some of that confusion by replacing 'e.g.,' by what it means in English: 'for instance,'. This will require a number of patches until 'e.g.' is appropriately replaced. Feedback on patch size for ease of review and commit processing would be appreciated.
Note: Frequently, the replace with 'for instance' requires the re-wrapping of docblocks and code comments to be near but less than 80 characters.
Comment | File | Size | Author |
---|---|---|---|
#4 | 2627018-4-fix-string-eg-d8.patch | 87.47 KB | Lars Toomre |
#4 | interdiff-2627018-4-2.txt | 17.88 KB | Lars Toomre |
Comments
Comment #2
Lars Toomre CreditAttribution: Lars Toomre commentedHere is an initial patch converting instances of 'e.g.' in thirty-four files. It does not convert any comments in *.js files nor does it touch any user facing strings.
Is this too big, about right or two small? if all of the patches for this conversion were this size, it would take about ten commits to eliminate the use of e.g. in docblock and code documentation.
Comment #3
jhodgdonRegarding patch size, I wouldn't make this type of patch any bigger than it is. I think it's about the right size.
And it's mostly wonderful! Thanks! A few small things to address...
In this case, I think we could just eliminate the e.g., since there is an etc. at the end of the list?
The punctuation here is incorrect. ; means "here's another clause of the sentence", but this isn't another clause.
Really the "for example, with an IN query" needs to I think be in ().
Extra space after .
Extra space after .
any => an
Hm. I don't think I like having two : in one sentence, perhaps leave these two lines as they were?
Probably the . should be a ; here?
and here
If we're fixing this up, we could also fix the comma splice (the last comma should be a ; ).
defaults for => defaults to
And why did you put the array in quotes? That makes no sense to me. Better to put in @code ... @endcode.
(Optional) should be lower-case
This last sentence rewrite was a bit confusing for me to read. I think maybe starting it with "When NULL (the default) is specified," might make it clearer that both the white and transparent mentions are for the default case? Because as it is now, the "the default" bit kind of looks like it's just for the "otherwise" clause.
For instance needs capitalization.
If we're fixing up this doc block, could we have a one-line summary to start it off?
Since it's in the same paragraph, want to also fix up the i.e. in this line?
In a previous issue, we got rid of ... in favor of etc. This one must have crept back in... also if you have ... or etc. you probably do not need "for example" in there also!
trailing space on this line.
Um. This line doesn't make any sense? Array with string containing with ?
Comment #4
Lars Toomre CreditAttribution: Lars Toomre commentedRe 3.2 - Sorry about the extra space. I am so used to starting a new sentence with double spacing that I do it habitually. I will try to be better, but I am sure that it will come up in other patches I submit for issues. Thanks for bearing with me.
Re 3.6 - I was not happy with the original construct. Hence, I turned it into a complete sentence.
Re 3.11 - This change may conflict with a change to the same line in one of the '(optional)' patches. I cannot find that patch quickly now, but included the suggested change in this patch as well.
Re 3.14 - Fixed up the description for the HIDDEN constant. TLC is needed on StreamWrapperInterface.php to clean up the other constants as well as full file standards review.
Re 3.15 - I am laughing. I was attempting to keep this issue strictly focused on 'e.g.' and avoid 'i.e.'. Fixed text as requested.
Re 3.18 - I was just focused originally of the 'e.g.' portion of the comment. In the future, I will also clean up any docblock issues that include a 'e.g.' string fix.
Attached is an interdiff and patch (with -U6 switch) that address the comments from #3.
Comment #5
jhodgdonThis is great! I'm going to go ahead and commit it to 8.0 and 8.1. That will likely conflict with your "optional" patch, but hopefully not too much.
A couple of notes:
Just as a note, and you didn't introduce this... The docs say it's a double-colon but the example only has one colon in bar:some_parameter... one of them must be wrong? Separate issue though.
Hm. Looking at the rest of the file I think it's a single colon. So I fixed this in the commit.
Much nicer thanks!
Comment #7
Lars Toomre CreditAttribution: Lars Toomre commentedThank you @jhodgon. I will start working shortly on the next incremental patch addressing 'e.g.'. My notes from this one include addressing the content of a docblock if it is touched and not just the 'e.g.' sub-string. Attempt to keep the patch size using -U6 switch around 50k in size. Anything else I missed?
Comment #8
jhodgdonNo, I thought this round went well! Thanks again!