New javadoc proposal (was: [Geotools-gt2-users] JavaDoc v2.2.M2 broken)

[Martin D. <mar...@no...>]

Jody Garnett a =E9crit :
>>> I have just downloaded GT2.2.M2, but the JavaDoc seems to be broken!
>>> For example I miss the index.html.
>>
>> We noticed this problem when we created the 2.2 build with Maven 1.=20
>> Even with -Xmx1024M, we have been unable to avoid an OutOfMemoryError=20
>> during javadoc generation. I plan to try to fix that with the Maven 2=20
>> build. Not sure when it will be ready however...
>=20
> Perhaps we could build *just* the api and main modules? Or even just ap=
i=20


I have generated a new set of javadoc using an Ant script (because Maven=20
1 produces an OutOfMemoryError, and Maven 2 do not yet produces a=20
cross-module javadoc). Temporary link here (to be moved elsewhere later):

     http://www.espace.ird.nc/~usespace/javadoc/geotools/

Request for opinions:

    * Any change proposal for the group content? (i.e. the packages to
      put in the "Data Stores" group, the packages to put in the "XML
      and derivatives (GML, SVG)" group, etc.)

    * Any change to the group names?

    * Any change to the group order (which ones to put first)?

    * Any packages or modules that should be excluded?

For developers:

    * Should I commit the ant script on SVN as a gt/build-javadoc.xml
      file (at the root of every modules)?

    * Should we put the javadoc on a different server?

    * I would like to define a @module tag to be added in every class
      description. This @module tag would just contains the name of the
      module that contains this class. I can make a Maven 2 plugin that
      put automatically the module name after the @module tag (it would
      modify the source). The goal is to have some hint in the javadoc
      about where a class can be found, since a single package is
      sometime splitted in many modules. Any agreement / objection?

    * javadoc generation produces 2382 warnings. A little bit of cleaning
      would be appreciated. (I already cleaned a lot in the referencing
      and coverage modules). For example if a method has a @return tag
      with no description, then I suggest to not put any @return tag at
      all. Just removing empty @return tags would solve many javadoc
      warnings.


	Martin.