Bruno Dumon wrote:
On Fri, 2005-06-17 at 17:15 +0200, Bertrand Delacretaz wrote:
Le 17 juin 05, à 17:08, Upayavira a écrit :
...a document detailing how the HTMLGenerator works, with all of its
options, wouldn't be that useful in other parts of the documentation
(other than as a link), IMO.
Agree. The reference section should be distinct from the tutorial
section ("section" meaning here either site of navigation subtree),
furthermore considering that a single component can be referenced from
several places in different tutorials.
IMHO such reference documents should have permanent and predictable
short URLs, say "reference/components/HTMLGenerator" in this case.
That's hoping these will be generated automatically of course, at some
point.
Depends a bit on what is part of the automatically-generated docs. IMHO
documentation that provides usage notes on components (thus, which is
not really javadoc) should better not be maintained as javadoc. For
example, take the I18nTransformer. There's a very very long javadoc
there which is essentially user documentation and is very hard to
read/maintain in the form of javadoc.
+1. A lot of components have their user docs in the javadoc as it wasn't
much harder to write it there rather than in xdocs. Things are different
now :-)
I am +1 though on merging technical information on the component (such a
it is cacheable, is it poolable, ...) automatically from the sources.
Yup.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
