Index: l10n.php
===================================================================
--- l10n.php	(revision 17501)
+++ l10n.php	(working copy)
@@ -52,23 +52,38 @@
 }
 
 /**
- * Retrieves the translation of $text. If there is no translation, or
- * the domain isn't loaded the original text is returned.
+ * Retrieves the translation of $text. If there is no translation, or the domain
+ * isn't loaded the original text is returned.
  *
- * @see __() Don't use translate() directly, use __()
+ * @see __() Don't use translate() directly, use __().
+ *
  * @since 2.2.0
- * @uses apply_filters() Calls 'gettext' on domain translated text
- *		with the untranslated text as second parameter.
  *
+ * @uses apply_filters() Calls 'gettext' on domain translated text with the
+ * untranslated text as second parameter.
+ *
  * @param string $text Text to translate.
- * @param string $domain Domain to retrieve the translated text.
- * @return string Translated text
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
  */
 function translate( $text, $domain = 'default' ) {
 	$translations = &get_translations_for_domain( $domain );
 	return apply_filters( 'gettext', $translations->translate( $text ), $text, $domain );
 }
 
+/**
+ * Removes last item on a pipe delimited string.
+ *
+ * Meant for removing the last item in a string like: 'Role name|User role'. It
+ * will return* the original string if no pipe '|' characters are found in
+ * the string.
+ *
+ * @since 2.7.0
+ *
+ * @param string $strimg A pipe delimited string.
+ * @return string Either $string or everything before last pipe.
+ */
 function before_last_bar( $string ) {
 	$last_bar = strrpos( $string, '|' );
 	if ( false == $last_bar )
@@ -77,6 +92,21 @@
 		return substr( $string, 0, $last_bar );
 }
 
+/**
+ * Retrieves the translation of $text in the context defined in $context. If
+ * there is no translation, or the domain isn't loaded the original text is
+ * returned.
+ *
+ * @since 2.8.0
+ * @see translate()
+ * @see _x()
+ *
+ * @param string $text Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
+ */
 function translate_with_gettext_context( $text, $context, $domain = 'default' ) {
 	$translations = &get_translations_for_domain( $domain );
 	return apply_filters( 'gettext_with_context', $translations->translate( $text, $context ), $text, $context, $domain );
@@ -86,43 +116,48 @@
  * Retrieves the translation of $text. If there is no translation, or
  * the domain isn't loaded the original text is returned.
  *
- * @see translate() An alias of translate()
+ * @see translate() An alias of translate().
  * @since 2.1.0
  *
- * @param string $text Text to translate
- * @param string $domain Optional. Domain to retrieve the translated text
- * @return string Translated text
+ * @param string $text Text to translate.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
  */
 function __( $text, $domain = 'default' ) {
 	return translate( $text, $domain );
 }
 
 /**
- * Retrieves the translation of $text and escapes it for safe use in an attribute.
- * If there is no translation, or the domain isn't loaded the original text is returned.
+ * Retrieves the translation of $text and escapes it for safe use in an
+ * attribute. If there is no translation, or the domain isn't loaded the
+ * original text is returned.
  *
- * @see translate() An alias of translate()
+ * @see translate() An alias of translate().
  * @see esc_attr()
  * @since 2.8.0
  *
- * @param string $text Text to translate
- * @param string $domain Optional. Domain to retrieve the translated text
- * @return string Translated text
+ * @param string $text Text to translate.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
  */
 function esc_attr__( $text, $domain = 'default' ) {
 	return esc_attr( translate( $text, $domain ) );
 }
 
 /**
- * Retrieves the translation of $text and escapes it for safe use in HTML output.
- * If there is no translation, or the domain isn't loaded the original text is returned.
+ * Retrieves the translation of $text and escapes it for safe use in HTML
+ * output. If there is no translation, or the domain isn't loaded the original
+ * text is returned.
  *
- * @see translate() An alias of translate()
+ * @see translate() An alias of translate().
  * @see esc_html()
  * @since 2.8.0
  *
  * @param string $text Text to translate
- * @param string $domain Optional. Domain to retrieve the translated text
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
  * @return string Translated text
  */
 function esc_html__( $text, $domain = 'default' ) {
@@ -132,11 +167,12 @@
 /**
  * Displays the returned translated text from translate().
  *
- * @see translate() Echoes returned translate() string
+ * @see translate() Echoes returned translate() string.
  * @since 1.2.0
  *
- * @param string $text Text to translate
- * @param string $domain Optional. Domain to retrieve the translated text
+ * @param string $text Text to translate.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
  */
 function _e( $text, $domain = 'default' ) {
 	echo translate( $text, $domain );
@@ -145,12 +181,13 @@
 /**
  * Displays translated text that has been escaped for safe use in an attribute.
  *
- * @see translate() Echoes returned translate() string
+ * @see translate() Echoes returned translate() string.
  * @see esc_attr()
  * @since 2.8.0
  *
- * @param string $text Text to translate
- * @param string $domain Optional. Domain to retrieve the translated text
+ * @param string $text Text to translate.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
  */
 function esc_attr_e( $text, $domain = 'default' ) {
 	echo esc_attr( translate( $text, $domain ) );
@@ -159,19 +196,20 @@
 /**
  * Displays translated text that has been escaped for safe use in HTML output.
  *
- * @see translate() Echoes returned translate() string
+ * @see translate() Echoes returned translate() string.
  * @see esc_html()
  * @since 2.8.0
  *
- * @param string $text Text to translate
- * @param string $domain Optional. Domain to retrieve the translated text
+ * @param string $text Text to translate.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
  */
 function esc_html_e( $text, $domain = 'default' ) {
 	echo esc_html( translate( $text, $domain ) );
 }
 
 /**
- * Retrieve translated string with gettext context
+ * Retrieve translated string with gettext context.
  *
  * Quite a few times, there will be collisions with similar translatable text
  * found in more than two places but with different translated context.
@@ -181,34 +219,65 @@
  *
  * @since 2.8.0
  *
- * @param string $text Text to translate
- * @param string $context Context information for the translators
- * @param string $domain Optional. Domain to retrieve the translated text
- * @return string Translated context string without pipe
+ * @param string $text Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
  */
 function _x( $single, $context, $domain = 'default' ) {
 	return translate_with_gettext_context( $single, $context, $domain );
 }
 
 /**
- * Displays translated string with gettext context
+ * Displays translated string with gettext context.
  *
  * @see _x
  * @since 3.0.0
  *
- * @param string $text Text to translate
- * @param string $context Context information for the translators
- * @param string $domain Optional. Domain to retrieve the translated text
- * @return string Translated context string without pipe
+ * @param string $single Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
  */
 function _ex( $single, $context, $domain = 'default' ) {
 	echo _x( $single, $context, $domain );
 }
 
+/**
+ * Displays translated string with gettext context after escaping for HTML.
+ *
+ * @see translate() An alias of translate().
+ * @see esc_attr()
+ *
+ * @since 3.0.0
+ *
+ * @param string $single Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
+ */
 function esc_attr_x( $single, $context, $domain = 'default' ) {
 	return esc_attr( translate_with_gettext_context( $single, $context, $domain ) );
 }
 
+/**
+ * Displays translated string with gettext context after escaping for HTML
+ * attributes.
+ *
+ * @see translate() An alias of translate().
+ * @see esc_html()
+ *
+ * @since 3.0.0
+ *
+ * @param string $single Text to translate.
+ * @param string $context Context information for the translators.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Translated text.
+ */
 function esc_html_x( $single, $context, $domain = 'default' ) {
 	return esc_html( translate_with_gettext_context( $single, $context, $domain ) );
 }
@@ -226,13 +295,14 @@
  *
  * @since 2.8.0
  * @uses $l10n Gets list of domain translated string (gettext_reader) objects
- * @uses apply_filters() Calls 'ngettext' hook on domains text returned,
- *		along with $single, $plural, and $number parameters. Expected to return string.
+ * @uses apply_filters() Calls 'ngettext' hook on domains text returned, along
+ *  with $single, $plural, and $number parameters. Expected to return string.
  *
- * @param string $single The text that will be used if $number is 1
- * @param string $plural The text that will be used if $number is not 1
- * @param int $number The number to compare against to use either $single or $plural
- * @param string $domain Optional. The domain identifier the text should be retrieved in
+ * @param string $single The text that will be used if $number is 1.
+ * @param string $plural The text that will be used if $number is not 1.
+ * @param int $number 1 for $single, plural otherwise.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
  * @return string Either $single or $plural translated text
  */
 function _n( $single, $plural, $number, $domain = 'default' ) {
@@ -247,6 +317,15 @@
  * @see _n()
  * @see _x()
  *
+ * @since 2.8.0
+ *
+ * @param string $single The text that will be used if $number is 1.
+ * @param string $plural The text that will be used if $number is not 1.
+ * @param int $number 1 for $single, plural otherwise.
+ * @param string $context Context information for the translators.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Either $single or $plural translated text.
  */
 function _nx($single, $plural, $number, $context, $domain = 'default') {
 	$translations = &get_translations_for_domain( $domain );
@@ -269,10 +348,12 @@
  *  $message = $messages[$type];
  *  $usable_text = sprintf( translate_nooped_plural( $message, $count ), $count );
  *
+ * @see _nx_noop()
  * @since 2.5
- * @param string $single Single form to be i18ned
- * @param string $plural Plural form to be i18ned
- * @return array array($single, $plural)
+ *
+ * @param string $singular singular form to be i18ned.
+ * @param string $plural Plural form to be i18ned.
+ * @return array array( $single, $plural ).
  */
 function _n_noop( $singular, $plural ) {
 	return array( 0 => $singular, 1 => $plural, 'singular' => $singular, 'plural' => $plural, 'context' => null );
@@ -282,6 +363,12 @@
  * Register plural strings with context in POT file, but don't translate them.
  *
  * @see _n_noop()
+ * @since 2.5
+ *
+ * @param string $singular singular form to be i18ned.
+ * @param string $plural Plural form to be i18ned.
+ * @param string $context Context information for the translators.
+ * @return array array( $single, $plural ).
  */
 function _nx_noop( $singular, $plural, $context ) {
 	return array( 0 => $singular, 1 => $plural, 2 => $context, 'singular' => $singular, 'plural' => $plural, 'context' => $context );
@@ -291,9 +378,14 @@
  * Translate the result of _n_noop() or _nx_noop()
  *
  * @since 3.1
- * @param array $nooped_plural array with singular, plural and context keys, usually the result of _n_noop() or _nx_noop()
- * @param int $count number of objects
- * @param string $domain Optional. The domain identifier the text should be retrieved in
+ *
+ * @param array $nooped_plural array with singular, plural and context keys,
+ *  usually the result of _n_noop() or _nx_noop().
+ * @param int $count Number of objects.
+ * @param string $domain Optional. Unique identifier for retrieving translated
+ *  strings.
+ * @return string Either $nooped_plural['singular'] or $nooped_plural['plural']
+ *  translated text.
  */
 function translate_nooped_plural( $nooped_plural, $count, $domain = 'default' ) {
 	if ( $nooped_plural['context'] )
@@ -305,18 +397,18 @@
 /**
  * Loads a MO file into the domain $domain.
  *
- * If the domain already exists, the translations will be merged. If both
- * sets have the same string, the translation from the original value will be taken.
+ * If the domain already exists, the translations will be merged. If both sets
+ * have the same string, the translation from the original value will be taken.
  *
- * On success, the .mo file will be placed in the $l10n global by $domain
- * and will be a MO object.
+ * On success, the .mo file will be placed in the $l10n global by $domain and
+ * will be a MO object.
  *
  * @since 1.5.0
- * @uses $l10n Gets list of domain translated string objects
+ * @uses $l10n Gets list of domain translated string objects.
  *
- * @param string $domain Unique identifier for retrieving translated strings
- * @param string $mofile Path to the .mo file
- * @return bool true on success, false on failure
+ * @param string $domain Unique identifier for retrieving translated  strings.
+ * @param string $mofile Path to the .mo file.
+ * @return bool true on success, false on failure.
  */
 function load_textdomain( $domain, $mofile ) {
 	global $l10n;
@@ -345,11 +437,12 @@
 }
 
 /**
- * Unloads translations for a domain
+ * Unloads translations for a domain.
  *
  * @since 3.0.0
- * @param string $domain Textdomain to be unloaded
- * @return bool Whether textdomain was unloaded
+ *
+ * @param string $domain Text domain to be unloaded.
+ * @return bool Whether text domain was unloaded.
  */
 function unload_textdomain( $domain ) {
 	global $l10n;
@@ -391,14 +484,17 @@
  * Loads the plugin's translated strings.
  *
  * If the path is not given then it will be the root of the plugin directory.
- * The .mo file should be named based on the domain with a dash, and then the locale exactly.
+ * The .mo file should be named based on the domain with a dash, and then the
+ * locale exactly.
  *
  * @since 1.5.0
  *
- * @param string $domain Unique identifier for retrieving translated strings
+ * @param string $domain Unique identifier for retrieving translated strings.
  * @param string $abs_rel_path Optional. Relative path to ABSPATH of a folder,
- * 	where the .mo file resides. Deprecated, but still functional until 2.7
- * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR. This is the preferred argument to use. It takes precendence over $abs_rel_path
+ * 	where the .mo file resides. Deprecated, but still functional until 2.7.
+ * @param string $plugin_rel_path Optional. Relative path to WP_PLUGIN_DIR.
+ *  This is the preferred argument to use. It takes precendence over $abs_rel_path.
+ * @return bool true on success, false on failure.
  */
 function load_plugin_textdomain( $domain, $abs_rel_path = false, $plugin_rel_path = false ) {
 	$locale = apply_filters( 'plugin_locale', get_locale(), $domain );
@@ -421,9 +517,10 @@
  *
  * @since 3.0.0
  *
- * @param string $domain Unique identifier for retrieving translated strings
- * @param strings $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in which
- * the MO file resides. Defaults is empty string.
+ * @param string $domain Unique identifier for retrieving translated strings.
+ * @param strings $mu_plugin_rel_path Relative to WPMU_PLUGIN_DIR directory in
+ *  which * the MO file resides. Defaults is empty string.
+ * @return bool true on success, false on failure.
  */
 function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) {
 	$locale = apply_filters( 'plugin_locale', get_locale(), $domain );
@@ -441,7 +538,8 @@
  *
  * @since 1.5.0
  *
- * @param string $domain Unique identifier for retrieving translated strings
+ * @param string $domain Unique identifier for retrieving translated strings.
+ * @return bool true on success, false on failure.
  */
 function load_theme_textdomain( $domain, $path = false ) {
 	$locale = apply_filters( 'theme_locale', get_locale(), $domain );
@@ -455,14 +553,16 @@
 /**
  * Loads the child themes translated strings.
  *
- * If the current locale exists as a .mo file in the child themes root directory, it
- * will be included in the translated strings by the $domain.
+ * If the current locale exists as a .mo file in the child themes root
+ * directory, it will be included in the translated strings by the $domain.
  *
  * The .mo files must be named based on the locale exactly.
  *
  * @since 2.9.0
  *
- * @param string $domain Unique identifier for retrieving translated strings
+ * @param string $domain Unique identifier for retrieving translated strings.
+ * @param string|bool $path Optional. Path to chlid theme directory of false.
+ * @return bool true on success, false on failure.
  */
 function load_child_theme_textdomain( $domain, $path = false ) {
 	$locale = apply_filters( 'theme_locale', get_locale(), $domain );
@@ -477,8 +577,12 @@
  * Returns the Translations instance for a domain. If there isn't one,
  * returns empty Translations instance.
  *
- * @param string $domain
- * @return object A Translation instance
+ * @see NOOP_Translations class.
+ *
+ * @since 3.0.0
+ *
+ * @param string $domain Unique identifier for retrieving translated strings.
+ * @return object A Translation instance.
  */
 function &get_translations_for_domain( $domain ) {
 	global $l10n;
@@ -489,11 +593,12 @@
 }
 
 /**
- * Whether there are translations for the domain
+ * Whether there are translations for the domain.
  *
  * @since 3.0.0
- * @param string $domain
- * @return bool Whether there are translations
+ *
+ * @param string $domain Unique identifier for retrieving translated strings.
+ * @return bool Whether there are translations.
  */
 function is_textdomain_loaded( $domain ) {
 	global $l10n;
@@ -509,18 +614,27 @@
  * using the old context format: 'Role name|User role' and just skipping the
  * content after the last bar is easier than fixing them in the DB. New installs
  * won't suffer from that problem.
+ *
+ * @since 2.8.0
+ *
+ * @param string $name A pipe delimited string.
+ * @return string Translated text.
  */
 function translate_user_role( $name ) {
 	return translate_with_gettext_context( before_last_bar($name), 'User role' );
 }
 
 /**
- * Get all available languages based on the presence of *.mo files in a given directory. The default directory is WP_LANG_DIR.
+ * Get all available languages based on the presence of *.mo files in a given
+ * directory. The default directory is WP_LANG_DIR.
  *
  * @since 3.0.0
  *
- * @param string $dir A directory in which to search for language files. The default directory is WP_LANG_DIR.
- * @return array Array of language codes or an empty array if no languages are present.  Language codes are formed by stripping the .mo extension from the language file names.
+ * @param string $dir A directory in which to search for language files. The
+ *  default directory is WP_LANG_DIR.
+ * @return array Array of language codes or an empty array if no languages are
+ *  present. Language codes are formed by stripping the .mo extension from the
+ *  language file names.
  */
 function get_available_languages( $dir = null ) {
 	$languages = array();
@@ -532,4 +646,4 @@
 	}
 
 	return $languages;
-}
\ No newline at end of file
+}