Merge pull request codeigniter4#8836 from kenjis/docs-improve-lang

docs: improve lang()

user_guide_src/source/general/common_functions.rst

@@ -106,13 +106,15 @@ Service Accessors
 
 .. php:function:: lang($line[, $args[, $locale]])
 
-    :param string $line: The line of text to retrieve
+    :param string $line: The language filename and the key of the text to retrieve.
     :param array  $args: An array of data to substitute for placeholders.
-    :param string $locale: Specify a different locale to be used instead of default one.
+    :param string $locale: Specify a different locale to be used instead of the current locale.
+    :returns: The text in the language file
+    :rtype: list<string>|string
 
-    Retrieves a locale-specific file based on an alias string.
+    Retrieves text from the language files.
 
-    For more information, see the :doc:`Localization </outgoing/localization>` page.
+    For more information, see the :ref:`language-localization`.
 
 .. php:function:: model($name[, $getShared = true[, &$conn = null]])
 

user_guide_src/source/outgoing/localization.rst

@@ -130,6 +130,8 @@ Alternatively, you can use the :doc:`Services class </concepts/services>` to ret
 
 .. literalinclude:: localization/006.php
 
+.. _language-localization:
+
 *********************
 Language Localization
 *********************
@@ -157,8 +159,10 @@ Basic Usage
 ===========
 
 You can use the :php:func:`lang()` helper function to retrieve text from any of the language files, by passing the
-filename and the language key as the first parameter, separated by a period (.). For example, to load the
-``errorEmailMissing`` string from the **Errors.php** language file, you would do the following:
+filename and the language key as the first parameter, separated by a period (``.``).
+
+For example, to load the ``errorEmailMissing`` string from the **Errors.php**
+language file, you would do the following:
 
 .. literalinclude:: localization/010.php
 
@@ -167,7 +171,7 @@ For nested definition, you would do the following:
 .. literalinclude:: localization/011.php
 
 If the requested language key doesn't exist in the file for the current locale, the string will be passed
-back, unchanged. In this example, it would return 'Errors.errorEmailMissing' or 'Errors.nested.error.message' if it didn't exist.
+back, unchanged. In this example, it would return ``Errors.errorEmailMissing`` or ``Errors.nested.error.message`` if it didn't exist.
 
 Replacing Parameters
 --------------------