Merge pull request #6543 from kenjis/fix-docs-model

docs: improve `model()` explanation

user_guide_src/source/changelogs/v4.0.0.rst

@@ -14,7 +14,7 @@ Enhancements:
 - Additional docs for getting started
 - CLI fixed to better handle complex arguments
 - Improvements to File class
-- New model() helper method for easy singleton Models.
+- New :php:func:`model()` helper method for easy singleton Models.
 - Tests completely reorganized to make app-level tests simpler out of the box.
 
 Repo changes:

user_guide_src/source/concepts/factories.rst

@@ -83,7 +83,7 @@ The first is ``config()`` which returns a new instance of a Config class. The on
 model()
 =======
 
-The second function, ``model()`` returns a new instance of a Model class. The only required parameter is the class name:
+The second function, :php:func:`model()` returns a new instance of a Model class. The only required parameter is the class name:
 
 .. literalinclude:: factories/009.php
 

user_guide_src/source/general/common_functions.rst

@@ -101,11 +101,13 @@ Service Accessors
 
 .. php:function:: model($name[, $getShared = true[, &$conn = null]])
 
-    :param string                   $name:
-    :param boolean                  $getShared:
-    :param ConnectionInterface|null $conn:
+    :param string                   $name: The model classname.
+    :param boolean                  $getShared: Whether to return a shared instance.
+    :param ConnectionInterface|null $conn: The database connection.
     :returns: More simple way of getting model instances
-    :rtype: mixed
+    :rtype: object
+
+    See also the :ref:`Using CodeIgniter's Model <accessing-models>`.
 
 .. php:function:: old($key[, $default = null,[, $escape = 'html']])
 

user_guide_src/source/installation/upgrade_models.rst

@@ -24,7 +24,7 @@ Upgrade Guide
 2. Add this line just after the opening php tag: ``namespace App\Models;``.
 3. Below the ``namespace App\Models;`` line add this line: ``use CodeIgniter\Model;``.
 4. Replace ``extends CI_Model`` with ``extends Model``.
-5. Instead of CI3's ``$this->load->model(x);``, you would now use ``$this->x = new X();``, following namespaced conventions for your component. Alternatively, you can use the ``model()`` function: ``$this->x = model('X');``.
+5. Instead of CI3's ``$this->load->model(x);``, you would now use ``$this->x = new X();``, following namespaced conventions for your component. Alternatively, you can use the :php:func:`model()` function: ``$this->x = model('X');``.
 
 If you use sub-directories in your model structure you have to change the namespace according to that.
 Example: You have a version 3 model located in **application/models/users/user_contact.php** the namespace has to be ``namespace App\Models\Users;`` and the model path in the version 4 should look like this: **app/Models/Users/UserContact.php**

user_guide_src/source/models/model.rst

@@ -16,13 +16,15 @@ It comes out of the box with helper
 methods for much of the standard ways you would need to interact with a database table, including finding records,
 updating records, deleting records, and more.
 
+.. _accessing-models:
+
 Accessing Models
 ****************
 
 Models are typically stored in the ``app/Models`` directory. They should have a namespace that matches their
 location within the directory, like ``namespace App\Models``.
 
-You can access models within your classes by creating a new instance or using the ``model()`` helper function.
+You can access models within your classes by creating a new instance or using the :php:func:`model()` helper function.
 
 .. literalinclude:: model/001.php
 

user_guide_src/source/tutorial/news_section.rst

@@ -121,7 +121,7 @@ access to the current ``Request`` and ``Response`` objects, as well as the
 Next, there are two methods, one to view all news items, and one for a specific
 news item.
 
-Next, the ``model()`` function is used to create the **NewsModel** instance.
+Next, the :php:func:`model()` function is used to create the **NewsModel** instance.
 This is a helper function. You can read more about it :doc:`here </general/common_functions>`.
 You could also write ``$model = new NewsModel();``, if you don't use it.