commons-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Craig R. McClanahan" <craig...@apache.org>
Subject Re: [Digester 1.5] Pattern matching screwed me up
Date Sun, 29 Feb 2004 17:56:59 GMT
Quoting Martin Kersten <Martin.Kersten@Student.Uni-Magdeburg.DE>:

> After going through it again, the JavaDoc API documents are
> available online statement, mention to read the package description. Maybe
> this should be said top level. The documentation is hidden within the API
> documentation. You know I just glaced over it and saw the api
> documentation is online. The second line didn't seam to be important at
> first...
> 

In the home page for Digester:

  http://jakarta.apache.org/commons/digester/

the second section of the overview is entitled "Documentation".  And the second
paragraph there states:

  The JavaDoc API Documents are available online.  In particular,
  you should read the package description for the
  org.apache.commons.digester package for detailed information
  on using the package.

I'm not sure how we can say it any more "top level" than that, but would
certainly be interested in any ideas there.  (A similar comment is made on the
first page of the JavaDocs themselves.)

On the general topic of including user guide documentation in the JavaDocs,
you'll find this to be quite common in the various Commons packages.  The
reasoning is that these packages are, after all, class libraries to be used by
developers, and those developers are going to need the JavaDocs in order to
understand the valid method signatures and so on, no matter what.  Too often,
I've seen cases where class libraries were documented separately, and the user
guide was never read because developers tended to think a "user guide" is for
the user of their own application, not for the library they are trying to use,
and wouldn't read it.  This way, all the information that a developer needs is
accessible in one place.

A separate benefit is that the user guide can contain direct links to the
detailed JavaDocs for the classes it talks about, because the directory
structure for where package.html files go is well defined.  Trying to do this
with separated user guides leads to much more fragile links, in my experience.

Thanks for your offer to help!

Craig McClanahan


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-user-help@jakarta.apache.org


Mime
View raw message