Travis Swicegood has a post questioning the value of the docblock. I have a deep sympathy with this sentiment.
Even on projects with extensive generated documentation, I find that kind of documentation to be of extremely low value. The problem with inline API documentation is that there is no sense of priority. Developers [...]