[wp-hackers] Proposal for a function commenting convention

Sun Oct 14 12:05:20 GMT 2007

1. Obviously the whole issue with Mike Purvis [1] 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.

File Level

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 
something.

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 [3].

6. @since Would be nice to know what version the file was added to 
WordPress.

7. I would suggest that a description of what the file's purpose is, in 
long description format with no short description.

Global Level

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.

Define Level

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 
function.
18. Required to label @global, if global variables are used in the 
function/method
19. Required to have @return if a value is returned.
20. Required to have @since, when known.

Examples/Tutorials

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 [2] 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.

[1] http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015553.html
[2] http://trac.wordpress.org/changeset/6200
[3] 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.

Jacob Santos

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: [1],[2],[3] and adding documentation
> where provided [4]
>
> 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
> specifies:
>
> 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!
>
> [1] http://trac.wordpress.org/changeset/6198
> [2] http://trac.wordpress.org/changeset/6199
> [3] http://trac.wordpress.org/changeset/6228
> [4] http://trac.wordpress.org/changeset/6200
>
> westi
> - --
> Peter Westwood
> http://blog.ftwr.co.uk
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.2 (MingW32)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
>
> iD8DBQFHEfc7VPRdzag0AcURAkNPAKC094f3EpNSd+3zRko37eU04/VWsACfUORh
> 3Z6piBsEwJ55H5YupJPzp6g=
> =Mu0l
> -----END PGP SIGNATURE-----
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>   