[wp-hackers] [PATCH] Documentation

[Rich Bowen]

Robert Deaton wrote:
> On 2/17/06, Rich Bowen <rbowen at rcbowen.com> wrote:
>> Carthik Sharma wrote:
>>> 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 think I've been won around to this syntax. I'm concerned, however,
>> with the notion that we'll only document long functions. This causes
>> them to be left out of the generated webpage entirely.
> 
> Like I said in the other thread, I will personally be documenting them
> anyways and submitting the patches, no matter how trivial the
> functions may be. Perhaps such will be a wakeup call in the sense that
> this function pollution crap could use some fixing as well.

Speaking of function pollution ...

I've been experimenting with Zend Studio, and in addition to practically
writing all the phpdoc for you, it also does code analysis for stuff
like variables that are never used, and code that is never executed. I
think if we're concerned about "bloat" we could stand to drop the
function or two that never gets used.

-- 
Rich Bowen
rbowen at rcbowen.com