[wp-hackers] [PATCH] Documentation

Rob r at robm.me.uk
Sun Feb 19 20:24:42 GMT 2006

Rich Bowen wrote:
> 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.
Functions might not be used in the core, but might provide useful API 
functions to plugins and thus need to remain.

Rob Miller
http://robm.me.uk/ | http://kantian.co.uk/

More information about the wp-hackers mailing list