[wp-hackers] [PATCH] Documentation

[Rob]

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/