|
From: | John Calcote |
Subject: | Re: Building prog first |
Date: | Mon, 22 Mar 2010 16:50:43 -0600 |
User-agent: | Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.9) Gecko/20100317 Thunderbird/3.0.4 |
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 tobe 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
[Prev in Thread] | Current Thread | [Next in Thread] |