Callback Documentation Style

[danielhoover]

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

[aschempp]

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

[aschempp]

Oh by the way, a lot of work has already been done by @eS-IT
https://github.com/contao/docs/pull/48/files

[bezin]

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?

[aschempp]

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 :-)

[bezin]

I'll start with that and see, how far I get ;)

[aschempp]

yay!