[wp-hackers] Inline documentation

[Abhay Kumar]

> > [snip]
> > * 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.

I like your suggestion better.

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

I guess but it's nicer to see in the code. I think we should be
conscientious about it.

> [snip]
> > * var
> > ** should be obvious
>
> Could be useful in classes I suppose, this one I could go either way on.

Definiately to be used in classes. It is more useful to put it as
formal comments rather than double slashed comments at the end of the
line.

> > * 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.
This would be for those functions that do indeed need to be documented
very well. This would especially be useful for API stuff.

- Abhay

--
Abhay Kumar
http://abhaykumar.net/