[wp-hackers] [PATCH] Documentation

[Craig]

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.


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.

Understand that I don't have any issue with your suggestion as it stands,
however I guess we are both approaching this from two interpretations of
needs. As I said, I don't expect a "War and Peace" explanation, but I do
need something that I can use to at least know what to do research for.

This is why Carthik right asserted that we need to agree on some terms of
reference and such prior to embarking upon the actual work. If it is
determined that the inline docs are appropriately done as per your API
notation, then so be it, but at this point, I know that there are at least
two people with two different concepts of what the ID project is for and
should accomplish.

I totally appreciate and understand your concerns regarding
"over-documentation" as well as doing a whole crapload of work that may
actually be rejected by those in charge of commits, and I whole-heartedly
agree that we cannot have that situation.

Craig.