Change script example for drupal_parse_info_file() from .css to .js [#1049528]

Comment	File	Size	Author
#8	drupal_parse_info_file_docs.patch	1.41 KB	sreynen

	cssjs.patch	715 bytes	sreynen

Comment #1

mr.baileys

Dutch

🇧🇪 (Ghent)

CreditAttribution: mr.baileys commented 4 February 2011 at 14:33

Status:

Active

» Needs work

Makes perfect sense. However, if we're editing this doxygen block anyway, we should make the list adhere to Doxygen and comments coding conventions: Lists, more specifically: "Each list item starts with the key, followed by a colon, followed by a space, followed by the key description. The key description starts with a capital letter and ends with a period."

edit: typo.

Log in or register to post comments

Comment #2

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 4 February 2011 at 15:05

Title:

Change script example for drupal_parse_info_file() from .css to .js

» Change script example for drupal_parse_info_file() from .css to .js and fix docblock generally

Also: the correct puncutation for "eg" is "e.g.", and it should be preceded by a semicolon and followed by a comma (it means "for example" and should be punctuated the same):

features: Features available; e.g., features[] = logo.

There seems to be more than just this wrong with this docblock -- some of the information is coming out at the end and some at the beginning of
http://api.drupal.org/api/drupal/includes--common.inc/function/drupal_pa...

Log in or register to post comments

Comment #3

sreynen CreditAttribution: sreynen commented 4 February 2011 at 15:42

Title:	Change script example for drupal_parse_info_file() from .css to .js and fix docblock generally	» Change script example for drupal_parse_info_file() from .css to .js
Status:	Needs work	» Needs review

We should avoid issue scope creep; I created #1051184: Fix doxygen formatting and punctuation in documentation for drupal_parse_info_file().

Log in or register to post comments

Comment #4

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 4 February 2011 at 15:44

Can't we just fix it all up at the same time? Normally, when a doc issue is filed, the fix includes a fix-up of the formatting of the docblock in question.

Log in or register to post comments

Comment #5

sreynen CreditAttribution: sreynen commented 4 February 2011 at 17:15

Some of us can fix it all at the same time; others can't. That's one of the problems with issue scope creep: it discourages less experienced and more casual contributors by requiring wider knowledge and participation. This is admittedly a minor example, but issue scope creep is something we should avoid where we can, and we can here.

Log in or register to post comments

Comment #6

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 4 February 2011 at 17:39

I see what you are saying, but the replacement line you are proposing is not up to our doc standards, so I find it difficult to accept the patch you are proposing. Probably someone else can do the rest of the edits.

Log in or register to post comments

Comment #7

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 6 February 2011 at 15:06

Status:

Needs review

» Needs work

Log in or register to post comments

Comment #8

sreynen CreditAttribution: sreynen commented 6 February 2011 at 19:49

Status:

Needs work

» Needs review

File	Size
drupal_parse_info_file_docs.patch	1.41 KB

I see now you're reviewing the code after the patch is committed rather than the patch itself. I still think this approach discourages contributions, but this probably isn't the best place to have that conversation. Attached patch has all suggested changes.