Functional Docs: wp-includes/load.php

[ericlewis]

In attachment:24886.diff​, a rough run through of all inline documentation and docblocks.

Beginning this, I realize a (relatively) formalized syntax specific for WP core documentation would be helpful. There is a ​Pear Docblock comment standards which has some examples that can be considered.

[kpdesign]

The ​inline documentation standard from the Codex is being rewritten, and will be included in the Core Contributor Handbook (I need to incorporate DrewAPicture's suggested changes).

There's also a ​PHPDoc Tags Guide which lays out what the most-used tags are in WordPress inline docs, and how they are used. The Pear comment standards you referenced were used in creating the inline documentation standard currently in the Codex.

[ericlewis]

Replying to kpdesign:

The ​inline documentation standard from the Codex is being rewritten, and will be included in the Core Contributor Handbook (I need to incorporate DrewAPicture's suggested changes).

I'd be glad to help with the effort, I'll check in with the docs team during the weekly chat this week.

[ericlewis]

In attachment:24886.1.diff​

reintroduce @globals declarations
remove unused global $text_direction declaration in wp_load_translations_early()

[DrewAPicture]

Notes on 24886.1.diff​:

This was generated before the inline docs standards were in place so a few things will need to change across the board:

• Periods on functional short descriptions
• Remove any new @uses tags
• @global, @param, @return need ending periods.
• space alignment types then $vars, then descriptions

Also:

• s/multisite/Multisite
• s/blog/site

[ericlewis]

I also added a bunch of @global tags in here. What did we decide about documenting globals? It was spoken about ​in IRC a few weeks ago, and @nacin suggested that @globals are "really easy to abuse," and @uses should be used extremely sparingly. I think that constitutes a decision for @uses, we should mention it in our PHP Inline Doc standards. However the use of @globals is still vague since we didn't make a decision on its suggested use.

Replying to DrewAPicture:

• s/multisite/Multisite

Should Multisite always be capitalized? Core inline documentation is split in this regard. The codex article ​Create A Network goes back and forth between capitals and non-caps. Using the term Multisite is generally an abbreviation for WordPress Multisite, so I would say let's change all our naming conventions here to capitals across the board.

[DrewAPicture]

This is fixed as of [28656]. Looks like it missed posting/closing the ticket.

Props ericlewis, DrewAPicture.