4 ms·

I think the point about auto-generated documentation being near worthless is an important one. A project I'm working on has a requirement that the documentation

by gr366 17y ago

I think the point about auto-generated documentation being near worthless is an important one. A project I'm working on has a requirement that the documentation be auto-generated and available at a URL on the build server, but nobody reads it. The developers read the comments in the code itself, and the checklist people just check to see that it's there.

thwarted 17y ago
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 http://php.net/manual/en/book.spl.php and http://www.php.net/~helly/php/ext/spl/ 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.

4 ms·

I think the point about auto-generated documentation being near worthless is an important one. A project I'm working on has a requirement that the documentation

by gr366 17y ago

thwarted 17y ago
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 http://php.net/manual/en/book.spl.php and http://www.php.net/~helly/php/ext/spl/ 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.