[wp-hackers] Proposal for a function commenting convention
wordpress at santosj.name
Sun Oct 14 05:03:43 GMT 2007
Err, yeah. Have you any thoughts of how the version which functions were
added are going to be found? I'm not even sure the devs would know about
every function. You'll find that checking repository log is neat for
files, but doesn't really tell you much about functions. Unless of
course you check each repository commit.
(After some contemplation, one could perhaps, download or find an old
1.5 version and just start from there. Use the 1.5 version and just say
that any and all functions that existed in that version started with
that version and ignore the previous versions.)
Good luck with that. I would advise against trying it, because I can see
into the future and I can tell you straight up and right now that you're
not going to get very far before you give up. I know I would and you
would have to be completely diehard and god-like to do so. Meaning that
if you were to complete such a task, I would build a shine in your honor.
I think that going forward, it would be a good idea. Going back and
adding @since isn't going to do any good, since well, plugin authors
already know that their plugins don't work.
Besides that. I think that if you were (and by you, I mean we) going to
add phpDoc comments, it should also include information about the
function. What the function does and what it is used for and how in the
code is more useful than @since (not that I'm saying @since is useless,
because it isn't, it is more useful for future documentation than past).
In which case, I agree that the convention should be
* function_name() - Short description
* Long Description
* @param Stuff here
* @return Stuff here
* @since Version here (if known. Taxonomy should be updated to include
The reason for this convention is that the first thing a person wants to
know is what the function purpose is without the filler crap. The second
thing a coder wants to know after they've decided upon that, is more
about what it does and how to use it. If you are really hardcore, you'll
add (@example Code) or (@tutorial Text ... Code).
Meaning, while the "function_name()" portion is redundant in the
phpDocumentor context, it is still useful for the reader browsing the
code. You don't have to keep scrolling down to see what the function is,
it is just right there at the top!
I did some work on the Taxonomy documentation. I would like very much if
someone else would work on that. In that case, would it be neat if we
picked a file and assigned functions to whoever wants them to write
documentation for it? I'll be more willing to take up the task, if I
knew others were undergoing the same torture I was.
Jared Bangs wrote:
> On 10/13/07, Ozh <ozh at planetozh.com> wrote:
>> On 10/13/07, Robin Adrianse <robin.adr at gmail.com> wrote:
>>> PHPDoc has a @since variable, which was made specifically for this
>> But I'd really like at least a simple "// added in WP 2.4" even for
>> basic non phpdoc'ed stuff :)
> +1 for using PHPDoc as a standard way of doing this. If we're going to go
> back through and add comments to the existing code, it should definitely be
> in a consistent format.
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
More information about the wp-hackers