Docs standards for Bundled Themes

[DrewAPicture]

With the ​inline docs standards now in place, we need to bring the bundled themes up to standard. I've attached patches for Twenties Twelve and Thirteen. Do we need to do Twenties Ten and Eleven?

Twenty Fourteen will get its own docs review (#25257) when it's closer to release in 3.8.

[obenland]

Hey Drew, thanks for that. A couple of notes:

The short description of functions ​should always end with a period.

In twentytwelve.diff​:

• Can we update the docs, so that //duplicate_hook gets a space between the slashes and the word? Or would that break parsing? Looks ugly.
• In content-status.php: Filter says int, but passes a (legacy) string, we should change that to an int.
• In image.php: Would it satisfy the filter doc guidelines to not have the array passed as an argument to the filter, but still document the specific values? I understand that this is how the example in the guidelines work, but we should just omit the variable name in the documentation, IMO. (Same for Twenty Thirteen)

In twentythirteen.diff​:

• In functions.php: Is it the Customizer or the Theme Customizer?

[DrewAPicture]

Replying to obenland:

Hey Drew, thanks for that. A couple of notes:

The short description of functions ​should always end with a period.

Yeah, I think that may have still been up in the air when I did the patch. I'll fix it.

In twentytwelve.diff​:

• Can we update the docs, so that //duplicate_hook gets a space between the slashes and the word? Or would that break parsing? Looks ugly.

Needs to stay that way to as @nacin put it, make it "grep-able", besides, the parser, etc.

• In content-status.php: Filter says int, but passes a (legacy) string, we should change that to an int.

Will do.

• In image.php: Would it satisfy the filter doc guidelines to not have the array passed as an argument to the filter, but still document the specific values? I understand that this is how the example in the guidelines work, but we should just omit the variable name in the documentation, IMO. (Same for Twenty Thirteen)

I'll take a look.

In twentythirteen.diff​:

• In functions.php: Is it the Customizer or the Theme Customizer?

We should probably pick one. Is there an "official" name for it? Theme Customizer?

[DrewAPicture]

twentytwelve.2.diff​ incorporates fixes from comment:3

• Converted string value to int in the filter in content-status.php
• Passed the array of height/width values to the filter instead of a named variable
• Standardized "Theme Customizer" to just "Customizer"

twentythirteen.2.diff​ incorporates fixes from comment:3

• Passed the array of height/width values to the filter instead of a named variable
• Standardized "Theme Customizer" to just "Customizer"

[obenland]

Thanks for the update Drew. I think the only things missing are the periods that should not be removed.

[DrewAPicture]

Replying to obenland:

Thanks for the update Drew. I think the only things missing are the periods that should not be removed.

Good call. I must've generated these in limbo between making that decision for the standards. I'll regenerate the patches.

[DrewAPicture]

Replying to DrewAPicture:

Replying to obenland:

Thanks for the update Drew. I think the only things missing are the periods that should not be removed.

Good call. I must've generated these in limbo between making that decision for the standards. I'll regenerate the patches.

Actually, I take that back. File header short descriptions don't get periods. I thought you were referring to function descriptions.

[obenland]

Replying to DrewAPicture:

File header short descriptions don't get periods. I thought you were referring to function descriptions.

I'm sorry, but where is the logic in that? File headers don't but, function descriptions do?

[nacin]

Replying to obenland:

Replying to DrewAPicture:

File header short descriptions don't get periods. I thought you were referring to function descriptions.

I'm sorry, but where is the logic in that? File headers don't but, function descriptions do?

WordPress uses file descriptions as a headline or title, like "Bookmark Administration Functions". Function descriptions should be a complete sentence.

[lancewillett]

In 25521:

Twenty Twelve: update code comments to reflect WP inline docs standards. Props DrewAPicture, see #25256.

[lancewillett]

Looks like in the second Thirteen patch an extra closing parenthesis was added accidentally, see twentythirteen_the_attached_image:

$attachment_size     = apply_filters( 'twentythirteen_attachment_size', array( 724, 724 ) ) );

[lancewillett]

In 25522:

Twenty Thirteen: update code comments to reflect WP inline docs standards. Props DrewAPicture, see #25256.

[lancewillett]

Replying to DrewAPicture:

Do we need to do Twenties Ten and Eleven?

Sure, let's do back to Twenty Ten.

[DrewAPicture]

Replying to lancewillett:

Replying to DrewAPicture:

Do we need to do Twenties Ten and Eleven?

Sure, let's do back to Twenty Ten.

OK. I'll work on those this weekend.

[DrewAPicture]

Replying to lancewillett:

Replying to DrewAPicture:

Do we need to do Twenties Ten and Eleven?

Sure, let's do back to Twenty Ten.

See twentyten.diff​ and twentyeleven.diff​.

[lancewillett]

In 25625:

Twenty Eleven: update code comments to reflect WP inline docs standards. Props DrewAPicture, see #25256.

[lancewillett]

In 25627:

Twenty Ten: update code comments to reflect WP inline docs standards. Props DrewAPicture, closes #25256.

[ericlewis]

attachment:twentyten.2.diff​, attachment:twentyeleven.2.diff​, attachment:twentytwelve.3.diff​, attachment:twentythirteen.3.diff​ and attachment:twentyfourteen.diff​ bring the bundled themes in line with our ​new standard for multiline inline comments.

[johnbillion]

Why is the standard for a multiline comment different from the standard for a file header or a function docblock?

[DrewAPicture]

Replying to johnbillion:

Why is the standard for a multiline comment different from the standard for a file header or a function docblock?

Blocks starting with /* won't be parsed as a docblock.

[nacin]

In 25746:

Default themes: Don't use / docblocks for simple multiline comments.

props DrewAPicture, ericlewis.
fixes #25256.

[GaryJ]

Replying to johnbillion:

Why is the standard for a multiline comment different from the standard for a file header or a function docblock?

See ​https://gist.github.com/GaryJones/1ed130dcc0cdb025af0f#inline-comments for a little more explanation.

[nacin]

In 25908:

Translator comments are special, make sure they are parsed properly. see #25256.

[nacin]

In 25909:

Translator comments are special, make sure they are parsed properly. see #25256, for the 3.7 branch.