5.x Review method signatures

[dereuromark]

Many signatures are not even correct for 4.x but especially for 5.x types, e.g. $options is often an array type:

afterSave($event, $entity, $options = [])

.. php:staticmethod:: slug($string, $options = [])

.. php:staticmethod:: plugin($name, $options = [], $callback)

.. php:method:: deleteMany($entities, $options = [])

beforeSave(EventInterface $event, $entity, $options)

.. php:method:: controls(array $fields = [], $options = [])

.. php:method:: setPaginated($paginated, $options)

could all be typed in docs as they are in reality

I wonder if there is a more programmatic way to sync the docs to actual code?

[LordSimal]

Theoretically, if we could map this to https://api.cakephp.org we could maybe throw a build error when the mapped method doesn't exist. Then we can just do something like

.. php:method:: \Cake\ORM\Table::deleteMany

and the rest will come automatically.

But I am far too inexperienced with sphinx to do this kind of stuff so maybe @markstory can jump in here with some ideas

[markstory]

I can see two ways the signature linking could be implemeted:

1. As a separate tool that we run periodically to 'sync' signature from the code into RST docs.
2. Extending the phpdomain so that when sphinx is parsing RST data into an AST to build the docs, we could inject validation logic and fail the documentation build should the signatures diverge.

I think 1. is the better approach as we don't need CakePHP and its dependencies available to build the documentation, and the 'sync' tool could be used in CI to help ensure that docs stay current as we evolve the book and code.

[github-actions[bot]]

This issue is stale because it has been open for 120 days with no activity. Remove the stale label or comment or this will be closed in 15 days