From 48335c04bf8b96a9b8a80b222b58981515ec3ce7 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@odoo.com>
Date: Mon, 20 Jul 2020 08:49:56 +0000
Subject: [PATCH] [IMP] core: orm doc

* fix link from backend tutorial to log_access section
* flesh out log access documentation
* add documentation for log_access itself & improve doc for a few
  other model-level attributes
---
 doc/howtos/backend.rst |  4 ++--
 doc/reference/orm.rst  | 53 ++++++++++++++++++++++++++++++------------
 odoo/models.py         | 19 +++++++++++----
 3 files changed, 55 insertions(+), 21 deletions(-)

diff --git a/doc/howtos/backend.rst b/doc/howtos/backend.rst
index fddabf6cd95..b34bd5ddcaa 100644
--- a/doc/howtos/backend.rst
+++ b/doc/howtos/backend.rst
@@ -1775,8 +1775,8 @@ Examples can be easily adapted from XML-RPC to JSON-RPC.
     * http://pythonhosted.org/OdooRPC
     * https://github.com/abhishek-jaiswal/php-openerp-lib
 
-.. [#autofields] it is possible to :attr:`disable the automatic creation of some
-                 fields <odoo.models.Model._log_access>`
+.. [#autofields] it is possible to :ref:`disable the automatic creation of some
+                 fields <reference/fields/automatic/log_access>`
 .. [#rawsql] writing raw SQL queries is possible, but requires care as it
              bypasses all Odoo authentication and security mechanisms.
 
diff --git a/doc/reference/orm.rst b/doc/reference/orm.rst
index d705565b642..1ef0b5ca422 100644
--- a/doc/reference/orm.rst
+++ b/doc/reference/orm.rst
@@ -50,11 +50,20 @@ value::
 .. autoclass:: odoo.models.BaseModel()
 
     .. autoattribute:: _auto
+    .. attribute:: _log_access
+
+        Whether the ORM should automatically generate and update the
+        :ref:`reference/fields/automatic/log_access`.
+
+        Defaults to whatever value was set for :attr:`~._auto`.
+
     .. autoattribute:: _table
     .. autoattribute:: _sequence
     .. autoattribute:: _sql_constraints
 
     .. autoattribute:: _register
+    .. autoattribute:: _abstract
+    .. autoattribute:: _transient
 
     .. autoattribute:: _name
     .. autoattribute:: _description
@@ -70,14 +79,6 @@ value::
     .. autoattribute:: _parent_name
     .. autoattribute:: _parent_store
 
-    .. autoattribute:: _abstract
-
-    .. seealso:: :class:`odoo.models.AbstractModel`
-
-    .. autoattribute:: _transient
-
-    .. seealso:: :class:`odoo.models.TransientModel`
-
     .. autoattribute:: _date_name
     .. autoattribute:: _fold_name
 
@@ -91,11 +92,19 @@ Model
 
 .. autoclass:: odoo.models.Model()
 
+      .. autoattribute:: _auto
+      .. autoattribute:: _abstract
+      .. autoattribute:: _transient
+
 TransientModel
 --------------
 
 .. autoclass:: odoo.models.TransientModel()
 
+      .. autoattribute:: _auto
+      .. autoattribute:: _abstract
+      .. autoattribute:: _transient
+
 .. _reference/fields:
 .. _reference/orm/fields:
 
@@ -328,8 +337,6 @@ dependencies are modified.
 Automatic fields
 ----------------
 
-.. Documented
-
 .. attribute:: id
 
     Identifier :class:`field <odoo.fields.Field>`
@@ -338,23 +345,39 @@ Automatic fields
 
     Raise an Error otherwise.
 
-.. todo:: _log_access info
+.. _reference/fields/automatic/log_access:
+
+Access Log fields
+'''''''''''''''''
+
+These fields are automatically set and updated if
+:attr:`~odoo.models.BaseModel._log_access` is enabled. It can be
+disabled to avoid creating or updating those fields on tables for which they are
+not useful.
+
+By default, :attr:`~odoo.models.BaseModel._log_access` is set to the same value
+as :attr:`~odoo.models.BaseModel._auto`
 
 .. attribute:: create_date
 
-    :class:`~odoo.fields.Datetime`
+    Stores when the record was created, :class:`~odoo.fields.Datetime`
 
 .. attribute:: create_uid
 
-    :class:`~odoo.fields.Many2one`
+    Stores *who* created the record, :class:`~odoo.fields.Many2one` to a
+    ``res.users``.
 
 .. attribute:: write_date
 
-    :class:`~odoo.fields.Datetime`
+    Stores when the record was last updated, :class:`~odoo.fields.Datetime`
 
 .. attribute:: write_uid
 
-    :class:`~odoo.fields.Many2one`
+    Stores who last updated the record, :class:`~odoo.fields.Many2one` to a
+    ``res.users``.
+
+.. warning:: :attr:`~odoo.models.BaseModel._log_access` *must* be enabled on
+             :class:`~odoo.models.TransientModel`.
 
 .. _reference/orm/fields/reserved:
 
diff --git a/odoo/models.py b/odoo/models.py
index cf0cbf4c7c3..ba9cb15b6c4 100644
--- a/odoo/models.py
+++ b/odoo/models.py
@@ -260,16 +260,27 @@ class BaseModel(MetaModel('DummyModel', (object,), {'_register': False})):
     __slots__ = ['env', '_ids', '_prefetch_ids']
 
     _auto = False
-    """Whether a database table should be created (default: ``True``).
+    """Whether a database table should be created.
     If set to ``False``, override :meth:`~odoo.models.BaseModel.init`
     to create the database table.
 
+    Automatically defaults to `True` for :class:`Model` and
+    :class:`TransientModel`, `False` for :class:`AbstractModel`.
+
     .. tip:: To create a model without any table, inherit
             from :class:`~odoo.models.AbstractModel`.
     """
-    _register = False           #: not visible in ORM registry
-    _abstract = True            #: whether model is abstract
-    _transient = False          #: whether model is transient
+    _register = False           #: registry visibility
+    _abstract = True
+    """ Whether the model is *abstract*.
+
+    .. seealso:: :class:`AbstractModel`
+    """
+    _transient = False
+    """ Whether the model is *transient*.
+
+    .. seealso:: :class:`TransientModel`
+    """
 
     _name = None                #: the model name (in dot-notation, module namespace)
     _description = None         #: the model's informal name