Python documentation too difficult for beginners

[Lawrence D'Oliveiro]

In message <2010110223050345181-nizumzen at mcnuggetscom>, Nizumzen wrote:

> On 2010-11-02 10:42:22 +0000, jk said:
> 
>> I've been coding in PHP and Java for years, and their documentation is
>> concise, well structured and easy to scan.
> 
> Are you mad? Javadoc is one of the worst examples of source code
> documentation I can possibly imagine.

It appeals to corporate herds of code-cutter drones, though. It follows 
tedious rules that can be officially adopted as corporation policy, and 
cited as a conformance feature by third-party products that these 
corporations seem happy to spend money on. So the comments can be extracted 
from the code, sorted, collated, stamped, filed, indexed, and collated 
again, all as part of the make-work activity that seems to pass for actual 
productivity in so many big corporations.