API page: http://api.drupal.org/api/drupal/includes--bootstrap.inc/function/conf_p...
Describe the problem you have found:
The grammar, punctuation, and style for the conf_path() function doc is terrible. Such as:
"the remaining will ignored."
"Example for a fictitious site installed at http://www.drupal.org:8080/mysite/test/ the 'settings.php' is searched in the following directories:" (needs some punctuation, also examples are supposed to use example.com not drupal.org as per our style guides)
Probably more...
| Comment | File | Size | Author |
|---|---|---|---|
| #4 | 1071846-conf_path_doc_cleanup-2.patch | 3.45 KB | gbrands |
| #2 | 1071846-conf_path_doc_cleanup.patch | 3.05 KB | gbrands |
Comments
Comment #1
jhodgdonProbably a good project for a novice doc contributor who wants to learn about the standards...
Comment #2
gbrands commentedFirst shot at a patch, hope it works out. Let me know if I missed anything. I'm certainly not an English major...
Comment #3
jhodgdonThanks -- this is much better! I think it could still use a small amount of work:
a) Function doc first sentence should start with a 3rd-person verb: finds vs. find. See http://drupal.org/node/1354#functions -- and probably the next paragraph would then be clearer if it was 3rd-person verbs too.
b) I still think a word is missing in the 2nd paragraph, 2nd sentence. It's currently reading:
The first configuration file found will be used and the remaining will be ignored.
Maybe remaining *ones* will be ignored?
c) This sentence might be better with searched -> searched for:
With a site located at http://www.example.com:8080/mysite/test/, the file, settings.php, is searched in the following directories:
d) I didn't check this, but there may be a few lines that go past 80 characters in the line?
e) According to our standards (see link above), there should be a blank line between the @param section and the @return section.
Comment #4
gbrands commentedThanks for the quick feedback! I've implemented you suggestions and attached the new patch. I also double checked the 80 characters per line and none of them exceed that amount. The last two lines of the second paragraph are 80 chars exactly and the line you referred to is at 77 chars.
Thanks again!
Comment #5
jhodgdonExcellent! Thanks very much.
Ah. I just noticed this is still set at D7. It needs to go into d8 and d7. I'll change to d8 and click Retest to make sure it still applies to d8.
Comment #6
jhodgdon#4: 1071846-conf_path_doc_cleanup-2.patch queued for re-testing.
Comment #7
catchTagging.
Comment #8
webchickNice work! Committed to 8.x and 7.x.