[wp-hackers] Inline documentation

[Ryan Boren]

Robert Deaton wrote:
> -1, the codex is far too unreliable as far as I'm concerned, half the
> time its timing out, nowadays its been giving random 500 errors, the
> rest of the time its terribly slow. On being less readable, I think it
> has the advantage of being easier to read than shifting through all
> kinds of useless stuff for developers that's located on the codex,
> since it is geared more toward the end users than those developing the
> source.

In my experience, people developing the source mostly ignore inline 
documentation.  It just gets in the way.  I've been in shops where one 
of the most popular IDE drop-ins was a means to hide all of the annoying 
JavaDOC. Eliminate /** */ from my sight. Inline docs can be handy when 
first familiarizing yourself with a code base, but I prefer reading 
separate API docs for that if I bother reading anything besides what the 
source itself tells me.  I've written thousands of JavaDoc API comments 
and could certainly live with never doing it again.  They have a 
shelf-life of about two weeks after which they are hopelessly 
out-of-date due to the neglect and colossal indifference that follows 
the breathy flush of the original eagerness to document everything inline.

But, to each their own.  I'm fairly ambivalent as long as the format 
used makes it easy to hide inline docs in an IDE so that I don't have to 
scroll through all of it.  That's pretty easy with JavaDoc/PHPDoc.  I 
don't want to maintain it either, so maybe we could have an inline doc 
maintainer who commits updates.  And then a Wiki maintainer for syncing 
the online docs with the inline docs.  And then a bartender for mixing 
the drinks I'll need whenever I accidentally see JavaDoc in the source 
and flashback to the tedious "inline doc reviews" I had to endure for so 
many years.  "I think you should @see this other reference, blah, blah, 
blah.  You don't need to @raises here but you do need to here, blah, 
blah, blah."  Damn, I need a bourbon now. :-)

Ryan