[wp-hackers] [PATCH] Documentation

[Carthik Sharma]

On 2/17/06, Craig <nuclearmoose at gmail.com> wrote:
> On 2/17/06, Rich Bowen <rbowen at rcbowen.com> wrote:
> >
> >
> > I'm going for API documentation, not "use this to learn how to write
> > PHP" documentation. It is assumed that folks will be willing to learn
> > what the notation means. And once you've learned it, the docs become
> > clear.

Rich, I suppose we both agree we are working towards something that is
immediately useful to programmers. The benefit of using a system, such
as phpdocumentor, for one, is that people can read the same comments,
and browse the source at an automatically generated webpage. So it
might be better to adapt to an existing system rather than create a
new lingo (like it is better to use WP that to hand code a blog :) )

> I'm totally willing to learn what the notation means, but my concept of the
> inline documentation is a tool to help me figure out what a particular
> function is about. I'm not looking for a tutorial at every variable and
> array on where the data are coming from, how they are processed, and where
> they are going after that bit of code is executed. If I only have a short
> explanation, or indeed a label of some kind, then I know that I can search
> Codex for more detailed information.

Craig,
You will get the parameters(Variables), their "type", what they do,
and what the whole function does, which should be good enough, I
guess. All this, with the phpdocumentor style of commenting.

Carthik.
--
Ph.D. Candidate
University of Central Florida
Homepage: http://carthik.net