Agreed, with you and the author of the OP. I find the worst auto-generated documentation to be class hierarchies, which are problematic from the standpoint of trying to learn how to use a library (often because they lack working example code), and also problematic as a reference because the method lists are cluttered up with private and protected methods that you most likely shouldn't be aware of if you're using the public interface to a library, which is the reason you're reading the documentation to begin with. The lack of example code means you don't have a canonical idiom to use for reference and to build on, especially with things
As the author says, the django documentation is pretty strong. I've always thought PHP.net was an awesome documentation site/reference also, it's easy to browse and find stuff, even if the example code is sometimes messy and there's a bunch of wrong information in the 5+ year old comments. On the other hand, PHP decided to take the class hierarchy approach when documenting SPL. Thanks, ArrayIterator is a descendant of Iterator, but which methods do I need to define to actually create one. Both http://php.net/manual/en/book.spl.php and http://www.php.net/~helly/php/ext/spl/ , which has been a reference since before php.net had entries for this stuff, are a nightmare to try to learn from.
As the author says, the django documentation is pretty strong. I've always thought PHP.net was an awesome documentation site/reference also, it's easy to browse and find stuff, even if the example code is sometimes messy and there's a bunch of wrong information in the 5+ year old comments. On the other hand, PHP decided to take the class hierarchy approach when documenting SPL. Thanks, ArrayIterator is a descendant of Iterator, but which methods do I need to define to actually create one. Both http://php.net/manual/en/book.spl.php and http://www.php.net/~helly/php/ext/spl/ , which has been a reference since before php.net had entries for this stuff, are a nightmare to try to learn from.