[wp-hackers] Inline documentation

[Robert Deaton]

On 2/16/06, Abhay Kumar <lists at abhaykumar.net> wrote:
> > Let me add back in that I think many of the tags that are included
> > there should be omitted from WordPress. The author, copyright,
> > version, etc. aren't needed, just param and return really.
>
> My list of what I think should be included (including what was said
> above) and why:
> * deprecated
> ** it's useful and we already have depreciated functions that are commented.

I could see this being a useful flag

> * global
> ** it's always useful to define where the global variable was intially
> set. just good practice in general.

This may come in handy, although I think that a more easily readable
file on the codex that has a list of global variables, where they are
defined, modified, etc. would be more useful to everyone, as well as
the cross-references.

</snip>

> * since
> ** i know we have a subversion repository to track this but it's nice
> to see it in the code directly.

This adds extra load of keeping it up to date, and will probably screw
us over on meeting Matt's standards (heaven-forbid we add a tad bit of
size to the core), and so -1.

> * todo
> ** we already have this, might as well conform to a standard

+1, seems reasonable

> * var
> ** should be obvious

Could be useful in classes I suppose, this one I could go either way on.

> * link
> ** provide a link to the codex for a specific function

This is iffy, seems unnecessary, especially since a good deal of the
functions aren't documented properly or throughly enough.


--
--Robert Deaton
http://somethingunpredictable.com