Improving docblocks by including the new fieldList feature

src/ORM/Marshaller.php

@@ -82,9 +82,14 @@ protected function _buildPropertyMap($options) {
 /**
  * Hydrate one entity and its associated data.
  *
+ * ### Options:
+ *
+ * * associated: Associations listed here will be marshalled as well.
+ * * fiedlList: A whitelist of fields to be assigened to th entity, if not present
+ *   the accessible fields list in the entity will be used.
+ *
  * @param array $data The data to hydrate.
- * @param array $options List of options, if the 'associated' key is present
- * associations listed there will be marshalled as well.
+ * @param array $options List of options
  * @return \Cake\ORM\Entity
  * @see \Cake\ORM\Table::newEntity()
  */
@@ -152,9 +157,14 @@ protected function _marshalAssociation($assoc, $value, $options) {
 /**
  * Hydrate many entities and their associated data.
  *
+ * ### Options:
+ *
+ * * associated: Associations listed here will be marshalled as well.
+ * * fiedlList: A whitelist of fields to be assigened to th entity, if not present
+ *   the accessible fields list in the entity will be used.
+ *
  * @param array $data The data to hydrate.
- * @param array $options List of options, if the 'associated' key is present
- * associations listed there will be marshelled as well.
+ * @param array $options List of options
  * @return array An array of hydrated records.
  * @see \Cake\ORM\Table::newEntities()
  */
@@ -239,11 +249,16 @@ protected function _loadBelongsToMany($assoc, $ids) {
  * `$data` array will appear, those that can be matched by primary key will get
  * the data merged, but those that cannot, will be discarded.
  *
+ * ### Options:
+ *
+ * * associated: Associations listed here will be marshalled as well.
+ * * fiedlList: A whitelist of fields to be assigened to th entity, if not present
+ *   the accessible fields list in the entity will be used.
+ *
  * @param \Cake\Datasource\EntityInterface $entity the entity that will get the
  * data merged in
  * @param array $data key value list of fields to be merged into the entity
- * @param array $options List of options, if the 'associated' key is present
- * associations listed there will be marshalled as well.
+ * @param array $options List of options.
  * @return \Cake\Datasource\EntityInterface
  */
 	public function merge(EntityInterface $entity, array $data, array $options = []) {
@@ -303,11 +318,16 @@ public function merge(EntityInterface $entity, array $data, array $options = [])
  * `$data` array will appear, those that can be matched by primary key will get
  * the data merged, but those that cannot, will be discarded.
  *
+ * ### Options:
+ *
+ * * associated: Associations listed here will be marshalled as well.
+ * * fiedlList: A whitelist of fields to be assigened to th entity, if not present
+ *   the accessible fields list in the entity will be used.
+ *
  * @param array|\Traversable $entities the entities that will get the
  * data merged in
  * @param array $data list of arrays to be merged into the entities
- * @param array $options List of options, if the 'associated' key is present
- * associations listed there will be marshalled as well.
+ * @param array $options List of options.
  * @return array
  */
 	public function mergeMany($entities, array $data, array $options = []) {

src/ORM/Table.php

@@ -1609,6 +1609,17 @@ public function entityValidator() {
  * );
  * }}}
  *
+ * You can limit field that will be present in the constructed entity by
+ * passing the `fieldList` option, which is also accepted for associations:
+ *
+ * {{{
+ * $articles = $this->Articles->newEntity($this->request->data(), [
+ *	'fieldList' => ['title', 'body'],
+ *	'associated' => ['Tags', 'Comments.Users' => ['fieldList' => 'username']]
+ *	]
+ * );
+ * }}}
+ *
  */
 	public function newEntity(array $data = [], array $options = []) {
 		if (!isset($options['associated'])) {
@@ -1632,6 +1643,17 @@ public function newEntity(array $data = [], array $options = []) {
  * );
  * }}}
  *
+ * You can limit field that will be present in the constructed entities by
+ * passing the `fieldList` option, which is also accepted for associations:
+ *
+ * {{{
+ * $articles = $this->Articles->newEntities($this->request->data(), [
+ *	'fieldList' => ['title', 'body'],
+ *	'associated' => ['Tags', 'Comments.Users' => ['fieldList' => 'username']]
+ *	]
+ * );
+ * }}}
+ *
  */
 	public function newEntities(array $data, array $options = []) {
 		if (!isset($options['associated'])) {
@@ -1647,6 +1669,17 @@ public function newEntities(array $data, array $options = []) {
  * When merging HasMany or BelongsToMany associations, all the entities in the
  * `$data` array will appear, those that can be matched by primary key will get
  * the data merged, but those that cannot, will be discarded.
+ *
+ * You can limit field that will be present in the merged entity by
+ * passing the `fieldList` option, which is also accepted for associations:
+ *
+ * {{{
+ * $articles = $this->Articles->patchEntity($article, $this->request->data(), [
+ *	'fieldList' => ['title', 'body'],
+ *	'associated' => ['Tags', 'Comments.Users' => ['fieldList' => 'username']]
+ *	]
+ * );
+ * }}}
  */
 	public function patchEntity(EntityInterface $entity, array $data, array $options = []) {
 		if (!isset($options['associated'])) {
@@ -1666,6 +1699,17 @@ public function patchEntity(EntityInterface $entity, array $data, array $options
  * When merging HasMany or BelongsToMany associations, all the entities in the
  * `$data` array will appear, those that can be matched by primary key will get
  * the data merged, but those that cannot, will be discarded.
+ *
+ * You can limit field that will be present in the merged entities by
+ * passing the `fieldList` option, which is also accepted for associations:
+ *
+ * {{{
+ * $articles = $this->Articles->patchEntities($articles, $this->request->data(), [
+ *	'fieldList' => ['title', 'body'],
+ *	'associated' => ['Tags', 'Comments.Users' => ['fieldList' => 'username']]
+ *	]
+ * );
+ * }}}
  */
 	public function patchEntities($entities, array $data, array $options = []) {
 		if (!isset($options['associated'])) {