[wp-hackers] Inline Documentation Effort was a Failure

[Jacob Santos]

Matt wrote:
> On Wed, May 28, 2008 at 5:54 AM, Jacob Santos <wordpress at santosj.name> wrote:
>   
>> What I think you are wrong then, is that you aren't weighing the importance
>> of documentation compared to the small gain of its removal?
>>     
>
> I never said that. Documentation is helpful, but (probably going to
> start up some sort of flame war here :P ) wouldn't it be better if it
> was located in some sort of Developer-only docs (separate from the
> Codex, which would be end-user-oriented), rather than in the code? The
> just put a link to the docs in a comment above the function.
>   

You must forgive me, it is never my intention to ever start a flame war. 
With that in mind, when I do start "attacking" someone I always prepend 
the sentence with "I think..." to avert probable false accusations 
(however, I'm quite honest about what I think and I don't really care 
how you take it).

There is such a thing, it is called DocBook and it is an XML format. 
Luckily, phpdoc can be formatted in such a way as to output it. There is 
currently a Google Summer of Code project working with PhD, which I 
believe is a DocBook render (I'm unsure if it is real time like XSL, but 
the speed is considerable).

It has my interest and I look forward to looking more into it. If it is 
possible to output phpdoc into DocBook Format and then extend that to 
create as good as developer documentation as what php.net has, then I 
think it would be solid.

If that is the case, then it would be favorable to implement your 
suggestion, as the DocBook would be better at giving developers what 
they need, whereas the default phpdocumentor HTML output isn't very 
helpful, unless you know where and what you are looking for.

As an aside, there is likely a build process already or at least I hope 
someone isn't going in and taking them out by hand. The {@internal 
Missing Short Description}} are all removed from the distribution builds 
of WordPress.

-- 

Jacob Santos

http://www.santosj.name - blog
http://funcdoc.wordpress.com - WordPress Documentation Blog/Guide Licensed under GPLv2

Also known as darkdragon and santosj on WP trac.