Merge pull request #8587 from kenjis/docs-improve-model-entity

docs: improve Model and Entity

Author: kenjis

user_guide_src/source/models/entities.rst

@@ -60,12 +60,21 @@ Create the model first at **app/Models/UserModel.php** so that we can interact w
 
 .. literalinclude:: entities/002.php
 
-The model uses the ``users`` table in the database for all of its activities. We've set the ``$allowedFields`` property
-to include all of the fields that we want outside classes to change. The ``id``, ``created_at``, and ``updated_at`` fields
-are handled automatically by the class or the database, so we don't want to change those. Finally, we've set our Entity
-class as the ``$returnType``. This ensures that all methods on the model that return rows from the database will return
+The model uses the ``users`` table in the database for all of its activities.
+
+We've set the ``$allowedFields`` property to include all of the fields that we
+want outside classes to change. The ``id``, ``created_at``, and ``updated_at``
+fields are handled automatically by the class or the database, so we don't want
+to change those.
+
+Finally, we've set our Entity class as the ``$returnType``. This ensures that all
+built-in methods on the model that return rows from the database will return
 instances of our User Entity class instead of an object or array like normal.
 
+.. note::
+    Of course, if you add a custom method to your model, you must implement it
+    so that instances of ``$returnType`` are returned.
+
 Working with the Entity Class
 =============================
 

user_guide_src/source/models/model.rst

@@ -123,12 +123,16 @@ default value is ``true``.
 $returnType
 -----------
 
-The Model's CRUD methods will take a step of work away from you and automatically return
-the resulting data, instead of the Result object. This setting allows you to define
-the type of data that is returned. Valid values are '**array**' (the default), '**object**', or the **fully
-qualified name of a class** that can be used with the Result object's ``getCustomResultObject()``
-method. Using the special ``::class`` constant of the class will allow most IDEs to
-auto-complete the name and allow functions like refactoring to better understand your code.
+The Model's **find*()** methods will take a step of work away from you and automatically
+return the resulting data, instead of the Result object.
+
+This setting allows you to define the type of data that is returned. Valid values
+are '**array**' (the default), '**object**', or the **fully qualified name of a class**
+that can be used with the Result object's ``getCustomResultObject()`` method.
+
+Using the special ``::class`` constant of the class will allow most IDEs to
+auto-complete the name and allow functions like refactoring to better understand
+your code.
 
 .. _model-use-soft-deletes:
 
@@ -145,7 +149,7 @@ This requires either a DATETIME or INTEGER field in the database as per the mode
 `$dateFormat`_ setting. The default field name is ``deleted_at`` however this name can be
 configured to any name of your choice by using `$deletedField`_ property.
 
-.. important:: The ``deleted_at`` field must be nullable.
+.. important:: The ``deleted_at`` field in the database must be nullable.
 
 $allowedFields
 --------------