[wp-hackers] [PATCH] Documentation
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
>>>> 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.
http://robm.me.uk/ | http://kantian.co.uk/
More information about the wp-hackers