[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Building prog first

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: 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 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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]