Re: [Geotools-devel] New javadoc proposal

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

David Zwiers a =E9crit :
>> * 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?
>=20
> =20
> I think this is a good idea. Without looking at your build file, I have=
=20
> a few ideas. Is it posible to complete this during the compile cycle=20
> only (copy the src, augment the src , ... ), leaving a 'clean' svn=20
> repository?Ccould we take this one step farther, and include the=20
> intended target binary too (jar file name) ... it should be accessable=20
> when the build is happening.

It is possible, but my experience suggests that the copy step add a fair=20
amount of overhead, since it is 2748 files (24.2 megabytes) to copy. At=20
least for me it discourage a little bit frequent javadoc generation, and=20
concenquently the fix of javadoc warnings. If we add a @module tag in=20
the source and commit to SVN, it should be done only once (unless a=20
source file moves to an other module).

Adding the jar file name should not be hard; it can be done with a=20
custom taglet. I did one for GeoAPI a while ago, so I can make this one=20
for Geotools.

Actually, I think that it is possible (in theory) to avoid completly a=20
@module tag is we write a custom doclet. But I never tried to modify the=20
standard doclet and will probably miss time to learn.


> * 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.
>=20
> =20
> My Eclipse install has quite a few more than that ... it all depends on=
=20
> the compiler's settings.

A lot of javadoc warnings come from classes not found in the classpath.=20
The ant script (just commited a few minutes ago) should find most of the=20
classes, provided that a Maven 2 build has been executed before.


	Martin.