Improve inline docs for l10n functions

[CharlesClarkson]

Changes to the inline documentation in WordPress 3.1.

These are documentation changes only.

[CharlesClarkson]

Changes for Inline documentation in the l10n.php file.

[hakre]

Thanks for providing the patch. Which wordwrap setting have you used for the text in comments?

[CharlesClarkson]

Replying to hakre:

Which wordwrap setting have you used for the text in comments?

I wrapped at 80 characters. Except in lines 349 & 496. Is there a standard wrap for WordPress files?

[nacin]

Replying to CharlesClarkson:

Replying to hakre:

Which wordwrap setting have you used for the text in comments?

I wrapped at 80 characters. Except in lines 349 & 496. Is there a standard wrap for WordPress files?

Nope.

[ericlewis]

Patch needs refresh. A lot of this is word wrap changes and adding periods at the end of sentences.

Hopefully changes in word wrap and punctuation will get specific direction and instruction from the Inline Docs group early in the 3.7 cycle.

[DrewAPicture]

16750.diff​ builds off of and refreshes l10n.diff​ at r25449

[DrewAPicture]

Change 'Optional' style to standard use

[DrewAPicture]

16750.2.diff​ uses the 'Optional. ' style per the inline docs standards.

[SergeyBiryukov]

In 25458:

Update inline documentation for l10n functions. props CharlesClarkson, DrewAPicture. fixes #16750.

[DrewAPicture]

In 25492:

Add missing $path parameter phpdoc for load_theme_textdomain().

see #16750.

[ericlewis]

attachment:16750.3.diff​ is leftover from some work I did in #24212 that categorically belongs on this ticket.

All references to "domain" are replaced with "text domain" for more explicit helpful description. Descriptions in docblocks for $domain are simplified to "Text domain." rather then "Unique identifier for retrieving translated strings." which is a bit more confusing off the bat.

[SergeyBiryukov]

s/domain/text domain/ seems fine.

For the longer string, I'd suggest adding "Text domain" in front of it, rather than replacing it. There should still be some short description, and the "unique identifier" serves that well.

[ericlewis]

Replying to SergeyBiryukov:

s/domain/text domain/ seems fine.

For the longer string, I'd suggest adding "Text domain" in front of it, rather than replacing it. There should still be some short description, and the "unique identifier" serves that well.

Here I thought giving the entire name for the unique identifier (Text domain) is more helpful instead of telling that is a unique identifier. There are a lot of unique identifiers that get tossed around WP core (Post ID, taxonomy name, etc.), and developers can be expected to look up the l18n API to understand what a text domain is, and that a text domain should be a unique identifier, which is why I left it out. It's a grey area between where we expect developers to seek more complete documentation and brevity.

Please tell me if I'm getting too pedantic :)

[DrewAPicture]

In 25586:

Standardize usage of 'text domain' in inline documentation for wp-includes/l10n.php.

Props ericlewis, SergeyBiryukov.
Fixes #16750.