contao
Callback Documentation Style
Hello dear contao Team!
First of all (as always) congrats on your good work. I love contao. Keep up the good work!
I've noticed, that the documentation for callbacks is not that obvious or hasn't all necessary information displayed. Wouldn't it be nice if we would separate the callbacks from the normal tables (or add additional ones) and add additonal information? For instance:
| Parameter | Type | Description |
|---|---|---|
| $row | array | An array containing every column of that row. |
| $label | string | Label of that record |
| DataContainer $dc | DataContainer | The DataContainer Object |
| $args | array | The columns of the record (defined by fields in dca) |
Return Type: array Description: The changed $args array
And to add an example would be also a nice thing.
I know that one will find this information if he looks into the source code. But if you look at the manual this would be a valuable information.
I would add this information for the callbacks. But the question is if you are ok with that?
Kind regards Daniel
I totally agree with you the information is far from useful. What do you think if we'd build it the same as the hook documentation? https://contao.org/en/manual/3.4/customizing-contao.html#contao-hooks
Oh by the way, a lot of work has already been done by @es-it https://github.com/contao/docs/pull/48/files
We have several issues commenting on the callback documentation style as well as a PR with a proposed solution. I started working on #337 and came across that issue again, because those callbacks are hard to document within the current structure. The callack documentation as it is right now is rather useless. As already proposed, I agree with a documentation style similar to the hooks documentation. What about the PR of @es-it since it is 2.5 years old? Rework that one or starting from scratch?
If you want to take a lead in rewriting the callback documentation, that would be awesome! To me it does not matter if we continue on the branch or not, whatever is easier to you :-)