I've been talking to a few other phpdoc'ers about this subject, namely philip and Pollita (aswell as Joey Smith/TML). I was a bit perplexed about the way callbacks was handled in the manual, with there never being a definition (as such) of what one is, and how to use them.
I was going to write this, but philip then found pretty much exactly what needs to be said in types.xml (language.types.callback - child of the language.pseudo-types section).
Once that was done, I said that this should be referenced wherever callbacks are used, to keep it all uniform and neat, rather than each function that uses callbacks either having a copy and paste or a completely new piece of text on callbacks.
At this point, philip said that I should be using <type>callback</type> in the documentation and that it would link dynamically... fair enough, I set to work, on an all at once commit for all functions that use callbacks. (as philip requested)
Then I stumbled across an incosistency, and after discussing with Pollita and philip in #php.doc (EFnet) it was suggested I post here to ask the general opinion.
Here is the problem:
array-map.xml <methodparam><type>mixed</type><parameter>callback</parameter></methodparam>
ob-start.xml <methodparam choice="opt"><type>callback</type><parameter> output_callback </parameter></methodparam>
As you can see, one is using <type>callback</type> the other <type>mixed</type>, the reasons being obvious - a callback is just a string or an array... so the question here is, do we respect the callback type as its own which consists of 'mixed' data, or do we use mixed? I personally feel that callback is more descriptive. as I am going through all callback functions anyways, I will change them all to have the same, whatever is decided. I'm not entirely bothered which is chosen, so long as one is, and its stuck too.
I appreciate your thoughts on the entire contents of this e-mail, not just the type stuff in the latter parts.
- Davey
-- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
