5.x: clarify deep marshalling

[LordSimal]

As just discussed in Slack/Discord it is not clear, that these two method calls don't lead to the same result:

// works as expected
$entity = $this->patchEntity($entity, $data, ['associated' => ['First.Second', 'First.Third', 'First.Fourth']]);

// won't patch Second, Third and Four
$entity = $this->patchEntity($entity, $data, ['associated' => ['First' => ['Second', 'Third', 'Fourth']]]); 

One would image/expect that this array structure behaves the same as a e.g. contain() array structure but it doesn't.

This PR at least adjusts the docs generated for api.cakephp.org including 2 separate tests to make sure this actually works and to link to if someone has questions about it.

We should make this clearer in the Book as well

[markstory]

One would image/expect that this array structure behaves the same as a e.g. contain() array structure but it doesn't.

Maybe we should make the formats the same?

[LordSimal]

Maybe we should make the formats the same?

In the long run, yes
I have added it to the 6.0 ideas