cakephp/docs — pull request #585 by pafuinlu (2013-06-04 10:15:42+00:00)
Title: Update saving-your-data.rst

The wording of the description for ``create()`` was very vague, misleading, complicated to understand. The 2.3 API description of ``create()`` is much better, but still a bit lacking. After tracing through the code to discover just what ``create()`` actually does, when it does it, and then doing some tests of my own, I've written some changes to the description which more accurately and effectively communicate the true functionality.

1.) The previous description strongly hinted that ``create()`` actually had no effect on fields that ***"have already been set"*** prior to calling ``create()`` and only upon fields which ***"have already been set"***, which is not the case. Any data that is set prior to calling ``create()`` is actually overwritten completely. I've updated this description to accurately describe the true effect upon ``Model::$data``.

2.) I've added the fact that ``null`` may also be passed as the ``$data`` param, not just ``false``. This was in the API but not yet added here in the docs.

3.) I've added clarity to what happens when there are no database defaults AND no parameters passed for ``$data``. In this case, ``Model::$data`` is set to an empty array.

4.) I've added clarity to what happens when ``false`` or ``null`` are passed for ``$data``, regardless of there being any database defaults. In this case, ``Model::$data`` is set to an empty array.