[wp-hackers] Inline documentation

[Sam Angove]

On 3/31/06, Alex King <lists at alexking.org> wrote:
> I think the conversation should change to: What is the best way to
> create and maintain inline documentation if it won't be checked into
> core.

I was going to suggest that the focus shift to making a php.net-style
function reference -- completing [Owen's at RedAlt][1], say -- which
would help serve the same documentation need. It doesn't suffer from
the merging troubles that a branch might.

It's incredibly easy to extract function definitions etc. from PHP
files[^2], so the thing could auto-update from SVN. It could track
changes within functions between versions. At the very least, it could
ping the maintainers/interested people when functions are added or
removed -- it helps keep itself up to date. And it's trivial to extend
to include a comment system, link to tutorials or examples, detail
deprecated usage etc.

It's possible to generate the inline documention from the function
reference and insert it into the source code -- it's actually easier
than it is to extract the same data from the inline docs, IMO -- so
you end up in the same place, but from the opposite direction.

There's also no more need to restrict the documentation to @param and
@return, since docblocks can be written to order.


[1]: http://redalt.com/fn/the_content
[^2]: I assume that's what was done at Red Alt. Here's some output
from one I wrote a week or two ago to extract functions/classes/hooks:
http://rephrase.net/miscellany/06/wp202data.txt