On 3/22/2010 4:34 PM, Reuben Thomas wrote:
What about using a info browser to search through the manual?
I often do that. The trouble is that often what I want to know has to
be deduced from the manual, which is natural enough, because the
manual tends to be structured according to the structure of the
program it documents, rather than of the problems the user is trying
to solve. By using web searches I can often find people asking and
answering precisely the problem I'm trying to solve.
Reuben, you've just hit upon one of the two most significant problems
with Javadoc and the like (including doxygen, man pages, and info pages):
1. You have to already know the API to know where to look for help on
the API because the documentation is structured according to the API,
rather than according to the top 100 use cases.
2. Most people don't add more than method header comments to their
source code, which means there's often no concept documentation, just
method documentation, which is useless to people trying to learn the
API. This isn't always true. Some projects try hard to add concept docs
too, but just very few by comparison.
Just a comment.
John
