[wp-hackers] Proposal for a function commenting convention
wordpress at santosj.name
Sun Oct 14 12:05:20 GMT 2007
1. Obviously the whole issue with Mike Purvis  would require the
@since so that tag should go in where possible. If you mean for details
on how much version detail, I really would push for just 1.5, 2.0,
2.0.1, etc. #.#.# should be enough. Assume WordPress Mu has different
standard if they want to jump aboard.
2. Deprecated functions, globals can be handled with @deprecated tag.
3. Do not have phpdoc blocks for include/require functions, because
usually, the wording of the documentation is redundant anyway.
I would suggest that at the very least, that if we are going to do this
right the first time that at the minimum these should be added.
4. @license It means nothing to the code, but it does phpDocumentor
site. License.txt covers the full extent of the installation, but
wouldn't for phpDocumentor. Raise of hands, how many have actually
*read* license.txt? It might say that we owe our first born to Matt or
All it needs is a link to the GPL v2 site.
5. @category WordPress ("All your bases our belong to us") Means
nothing, but might help move issues with WordPress Mu documentation out
from WordPress documentation. Could also use @Package WordPress, if
@Package isn't going to be used for anything else .
6. @since Would be nice to know what version the file was added to
7. I would suggest that a description of what the file's purpose is, in
long description format with no short description.
I believe that globals should be documented, given the inherited public
nature they have. If you wish to tell people to not mess with them, then
that should also be public.
8. Requires at the very least @global
9. May also require @name in some cases.
10. May also require @deprecated.
11. Will require @since at the very least, when information is known.
Defines should be documented as much as possible. phpDoc blocks allow
for the blocks to be away from the area they are documenting, but that
shouldn't be relied on. Would have to try to get as close to the define
as possible without having too many changes to the code.
12. Requires short description, along with any helpful information on
what it can be used for.
13. Should also require @since for when the define was available.
Function / Class / Method Level
14. Require Short Description, in form of "function_name() - Short
Description text here"
15. Should have Long Description where needed, including examples. If
long description should be written, then comment should be added, either
"Do Documentation" or "Undocumented".
16.Should have @access private if no one else should touch the code
besides the internals of WordPress.
17. Required to have @param, if function/method parameters are used in
18. Required to label @global, if global variables are used in the
19. Required to have @return if a value is returned.
20. Required to have @since, when known.
21. Examples should be written in the long description and between
<code>...</code> tags. Tutorials should be linked to using the @see tag
with the link to the resource, should prefer codex.
22. @internal: This should be used to pass notes to readers of the code,
because most cases it won't be displayed on the phpDocumentor site.
On a related note, the hook tags I added to the taxonomy. I'm unsure
whether I want to keep them. It is practically worthless at this point
as it would require a custom tool. The hooks should and can be added to
the long description or as @tutorial/@example instead. I think that
when/if I go back to writing documentation for that I'll do that instead
and strip out the custom tags for hooks.
I really wish devs would review documentation and correct mistakes, I
really hate the wording of  and I wrote it! I could just die I could.
If I was a better writer, I would spend time rewording it to where it
doesn't completely suck. I can just imagine somebody reading it in the
future thinking, "How can the code be easier to read than the
description?" Oh yeah, I was really angry when I wrote it, probably why
it doesn't make sense, it was on purpose. My bad, I forgot.
 I can never get those things right. Probably should leave it up to
the devs, if you want to add them. Or add them at a later date when a
consensus is reached. I'll remove them from the diff.
Peter Westwood wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> Jacob wrote:
>> Test DIFF here: http://www.santosj.name/wp-settings.phpdoc.diff -
>> Comments, insults, suggestions welcome.
>> Some of what you suggestion could only be approved by Matt, Mark, etc as
>> it would be on them to enforce it. It would require they enforce it on
>> themselves, I doubt such a suggestion would make it through. Seeing as
>> the current style is (like it or not), code it and see if it breaks
>> anything, I doubt the paradigm like "code, iterate, freeze, test,
>> unfreeze, repeat" would work at this stage. Could send an email to Matt
>> though, but still doubtful as it would require a whole new coding style
>> and drastic change to development cycle.
> Improving the documentation is welcome.
> I have been trying to ensure that all new template tags/functions I add
> are documented when they go in: ,, and adding documentation
> where provided 
> However, before we start on a mass documentation spree of the
> undocumented code we really need to form a list of the tags we are going
> to use from those available in phpDoc and valid values where appropriate.
> It would be nice to see a proposal on the documentation format which
> 1. The set of @package tags we are going to use.
> 2. Whether or not we want to use @since and if so in how much detail do
> we go.
> 3. How we handle deprecated functions.
> If you have simple single function or file phpDoc patches that just add
> documentation get them on trac and assigned to me and I will review and
> check them in.
> Better documentation will benefit everyone!
>  http://trac.wordpress.org/changeset/6198
>  http://trac.wordpress.org/changeset/6199
>  http://trac.wordpress.org/changeset/6228
>  http://trac.wordpress.org/changeset/6200
> - --
> Peter Westwood
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.2 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
> -----END PGP SIGNATURE-----
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
More information about the wp-hackers