[wp-hackers] Inline Documentation Effort was a Failure

[Jason Webster]

I realize what you meant. This was in reply to Jorge's question:

"Or maybe the inline docs can be parsed and generated into an external
doc? As is the case with some documentation programs, maybe there's
something like this for PHP?"


I find, from experience, that maintaining inline code is *easier, *more reliable than external documentation. Use case: patch in one function, fixes an outstanding bug and maybe slightly changes the way something works. You can fix the docs right there, right then in the docblock above the function, and the patch itself can update the documentation, rather than the community relying on either you or someone else to update external docs, which (honestly) never really happens.

Just for giggles, everyone involved in this discussion should take a look at what is required of ZF contributors, w/r/t inline documentation:
<http://framework.zend.com/wiki/display/ZFDEV/ZF+Coding+Standards+%28RC%29#ZFCodingStandards%28RC%29-InlineDocumentation>

Matt wrote:
> On Wed, May 28, 2008 at 6:40 PM, Jason Webster <jason at intraffic.net> wrote:
>   
>> http://www.phpdoc.org/
>>     
>
> I meant not actually have the documentation in the code. Which also
> makes it easier for people to contribute to the docs, since they won't
> have to make a Trac ticket, a patch and then wait for it to be
> committed. Which is also less work for the people with commit access.
>
>
>