Added documentation regarding some cached ORM scenarios

docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md

@@ -186,6 +186,12 @@ $members = Player::get()->filter([
 Provided `filter` values are automatically escaped and do not require any escaping.
 [/info]
 
+[info]
+`DataObject::get()->byID()` and `DataObject::get_by_id()` achieve similar results, but the object returned by `DataObject::get_by_id()` is cached against a `static` property within `DataObject`.
+
+`DataObject::get_by_id()` is a legacy ORM method, and it is recommended that you use `DataObject::get()->byID()` wherever possible
+[/info]
+
 ## Lazy Loading
 
 The `ORM` doesn't actually execute the [SQLSelect](api:SilverStripe\ORM\Queries\SQLSelect) until you iterate on the result with a `foreach()` or `<% loop %>`.

src/ORM/DataList.php

@@ -926,6 +926,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Returns the first item in this DataList
      *
+     * The object returned is not cached, unlike {@link DataObject::get_one()}
+     *
      * @return DataObject
      */
     public function first()
@@ -939,7 +941,9 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Returns the last item in this DataList
      *
-     *  @return DataObject
+     * The object returned is not cached, unlike {@link DataObject::get_one()}
+     *
+     * @return DataObject
      */
     public function last()
     {
@@ -962,6 +966,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Find the first DataObject of this DataList where the given key = value
      *
+     * The object returned is not cached, unlike {@link DataObject::get_one()}
+     *
      * @param string $key
      * @param string $value
      * @return DataObject|null
@@ -998,6 +1004,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Return the first DataObject with the given ID
      *
+     * The object returned is not cached, unlike {@link DataObject::get_by_id()}
+     *
      * @param int $id
      * @return DataObject
      */
@@ -1244,6 +1252,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
     /**
      * Returns item stored in list with index $key
      *
+     * The object returned is not cached, unlike {@link DataObject::get_one()}
+     *
      * @param mixed $key
      * @return DataObject
      */

src/ORM/DataObject.php

@@ -3217,7 +3217,9 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
 
     /**
      * Return the first item matching the given query.
-     * All calls to get_one() are cached.
+     *
+     * The object returned is cached, unlike DataObject::get()->first() {@link DataList::first()}
+     * and DataObject::get()->last() {@link DataList::last()}
      *
      * The filter argument supports parameterised queries (see SQLSelect::addWhere() for syntax examples). Because
      * of that (and differently from e.g. DataList::filter()) you need to manually escape the field names:
@@ -3326,6 +3328,8 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
      * This can be called either via `DataObject::get_by_id(MyClass::class, $id)`
      * or `MyClass::get_by_id($id)`
      *
+     * The object returned is cached, unlike DataObject::get()->byID() {@link DataList::byID()}
+     *
      * @param string|int $classOrID The class of the object to be returned, or id if called on target class
      * @param int|bool $idOrCache The id of the element, or cache if called on target class
      * @param boolean $cache See {@link get_one()}