Re: [Geotools-devel] 2.2.0 javdocs still reference the wrong GeoAPI

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

Andrea Aime a =E9crit :
> Well, I have generated aggregated javadocs and noticed no problem, but=20
> did not any about problems with custom taglets.
> Martin, can you point me to the custom taglet that was failing?


There is an example of the output I was trying to get:

http://javadoc.geotools.fr/snapshot/org/geotools/referencing/operation/De=
faultMathTransformFactory.html

Scroll down just after the "Since" and "Authors" tags, before "Field Summ=
ary". We can see two new=20
tags: "Tutorial" and "Module". "Tutorial" is a very simple taglet expecti=
ng (in the Java code=20
source) the URL to the tutorial, and displaying in the Javadoc a clear ti=
tle instead of the URL. It=20
is basically just a convenient @see tag linking to the Geotools tutorial.

The "Module" tag is more interresting, and was a user request on the mail=
ing list (the problem being=20
that some users have a hard time to find in which JAR file a specific cla=
ss is defined). The trick=20
is to have the following in the class javadoc of all source files:

     @source $URL$

where $URL$ is automatically filled by SVN (so the information stay accur=
ate even if we move the=20
file around in SVN). The taglet performs some regular expression analysis=
 on the URL in order to=20
determine in which module this class live. The module name is then displa=
yed, together with a link=20
to Maven report for that module, etc.

Now there is the problem: this custom taglet is defined in gt/maven/javad=
oc. This module has the=20
following dependencies:

     maven-script-ant
     maven-plugin-tools-ant

Version 2.0.4 for both of them. Those dependencies depend in turn on some=
 older version of=20
maven-plugin-resources.

The latest maven-plugin-javadoc depends on latest maven-plugin-resources.=
 But latest=20
maven-plugin-resources conflict with the maven-plugin-resources version e=
xpected by=20
maven-plugin-tools-ant, thus resulting in a build failure in gt/maven/jav=
adoc module.

The workaround was to stick to an older version of maven-plugin-javadoc. =
But doing so, we lost many=20
of the enhancements provided in latest maven-plugin-javadoc. This is why =
large part of javadoc=20
configuration are currently commented out in gt/pom.xml file. I would rea=
lly like to uncomment them,=20
since they includes usefull configuration like package grouping.

There is the possible action I can see right now:

* Check if an update of maven-plugin-tools-ant (more revent then 2.0.4)
   is available on ibiblio.

* Or, get ride completly of maven-plugin-tools-ant in maven/javadoc (afte=
r all
   we should not need it anymore if the standard "maven javadoc" work wel=
l enough).
   This means removing the xml Ant files from maven/javadoc, but keep the=
 Taglet
   Java code.

* Need to find how to configure the javadoc plugin in the pom.xml file fo=
r
   using those taglets.

So in summary, the problem was a version conflict between the maven-plugi=
n-resources expected by=20
maven-plugin-javadoc and maven-plugin-tools-ant. But once solved, some ad=
justment may still be=20
needed in the javadoc plugin configuration in the pom.xml file.

	Martin.