From 372355f7798971f340015a69f2f584fd7b90a824 Mon Sep 17 00:00:00 2001
From: aheritier <aheritier@13f79535-47bb-0310-9956-ffa450edef68>
Date: Mon, 28 Jun 2004 23:14:24 +0000
Subject: [PATCH] - Add the property maven.javadoc.debug - MPJAVADOC-28
 partially fixed : @link tag not working with package names. - MPJAVADOC-29
 partially fixed : Packages list broken on jdk 1.3 for multiple packages.

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@115589 13f79535-47bb-0310-9956-ffa450edef68
---
 javadoc/plugin.jelly         | 339 ++++++++++++++++++++++++-----------
 javadoc/xdocs/changes.xml    |   3 +
 javadoc/xdocs/properties.xml |   8 +
 3 files changed, 244 insertions(+), 106 deletions(-)

diff --git a/javadoc/plugin.jelly b/javadoc/plugin.jelly
index 148d6e93..aa971ded 100644
--- a/javadoc/plugin.jelly
+++ b/javadoc/plugin.jelly
@@ -28,11 +28,179 @@
   xmlns:maven="jelly:maven"
   >
 
+  <!-- ================================================================== -->
+  <!-- Initialize plugin                                                  -->
+  <!-- ================================================================== -->
+  
+  <goal name="javadoc:init" prereqs="xdoc:init">
+    <!-- javadoc plugin properties -->
+    <maven:get var="maven.javadoc.additionalparam"  plugin="maven-javadoc-plugin" property="maven.javadoc.additionalparam"/>
+    <maven:get var="maven.javadoc.author"           plugin="maven-javadoc-plugin" property="maven.javadoc.author"/>
+    <maven:get var="maven.javadoc.customtags"       plugin="maven-javadoc-plugin" property="maven.javadoc.customtags"/>
+    <maven:get var="maven.javadoc.debug"            plugin="maven-javadoc-plugin" property="maven.javadoc.debug"/>
+    <maven:get var="maven.javadoc.destdir"          plugin="maven-javadoc-plugin" property="maven.javadoc.destdir"/>
+    <maven:get var="maven.javadoc.doclet"           plugin="maven-javadoc-plugin" property="maven.javadoc.doclet"/>
+    <maven:get var="maven.javadoc.docletpath"       plugin="maven-javadoc-plugin" property="maven.javadoc.docletpath"/>
+    <maven:get var="maven.javadoc.links"            plugin="maven-javadoc-plugin" property="maven.javadoc.links"/>
+    <maven:get var="maven.javadoc.locale"           plugin="maven-javadoc-plugin" property="maven.javadoc.locale"/>
+    <maven:get var="maven.javadoc.maxmemory"        plugin="maven-javadoc-plugin" property="maven.javadoc.maxmemory"/>
+    <maven:get var="maven.javadoc.mode.online"      plugin="maven-javadoc-plugin" property="maven.javadoc.mode.online"/>
+    <maven:get var="maven.javadoc.offlineLinks"     plugin="maven-javadoc-plugin" property="maven.javadoc.offlineLinks"/>
+    <maven:get var="maven.javadoc.overview"         plugin="maven-javadoc-plugin" property="maven.javadoc.overview"/>
+    <maven:get var="maven.javadoc.package"          plugin="maven-javadoc-plugin" property="maven.javadoc.package"/>
+    <maven:get var="maven.javadoc.private"          plugin="maven-javadoc-plugin" property="maven.javadoc.private"/>
+    <maven:get var="maven.javadoc.public"           plugin="maven-javadoc-plugin" property="maven.javadoc.public"/>
+    <maven:get var="maven.javadoc.source"           plugin="maven-javadoc-plugin" property="maven.javadoc.source"/>
+    <maven:get var="maven.javadoc.stylesheet"       plugin="maven-javadoc-plugin" property="maven.javadoc.stylesheet"/>
+    <maven:get var="maven.javadoc.tagletpath"       plugin="maven-javadoc-plugin" property="maven.javadoc.tagletpath"/>
+    <maven:get var="maven.javadoc.taglets"          plugin="maven-javadoc-plugin" property="maven.javadoc.taglets"/>
+    <maven:get var="maven.javadoc.use"              plugin="maven-javadoc-plugin" property="maven.javadoc.use"/>
+    <maven:get var="maven.javadoc.useexternalfile"  plugin="maven-javadoc-plugin" property="maven.javadoc.useexternalfile"/>
+    <maven:get var="maven.javadoc.version"          plugin="maven-javadoc-plugin" property="maven.javadoc.version"/>
+    <maven:get var="maven.javadoc.windowtitle"      plugin="maven-javadoc-plugin" property="maven.javadoc.windowtitle"/>
+    
+    <!-- internal variables -->
+    <j:set var="internal.javadoc.jar"               value="${maven.build.dir}/${maven.final.name}_javadoc.jar"/>
+    <j:set var="internal.javadoc.needed"            value="null"/>
+    <j:set var="internal.javadoc.src.modifs"        value="false"/>
+    <j:set var="internal.javadoc.src.set"           value="${context.getAntProject().getReferences().get('maven.compile.src.set')}"/>
+    <j:set var="internal.javadoc.working.dir"       value="${maven.build.dir}/javadoc"/>
+   
+    <j:if test="${maven.javadoc.debug}">
+      <ant:echo>
+### Debug mode is on ###
+==================================
+=== javadoc plugin properties  ===
+==================================
+maven.javadoc.additionalparam   = [${maven.javadoc.additionalparam}]
+maven.javadoc.author            = [${maven.javadoc.author}]
+maven.javadoc.customtags        = [${maven.javadoc.customtags}]
+maven.javadoc.debug             = [${maven.javadoc.debug}]
+maven.javadoc.destdir           = [${maven.javadoc.destdir}]
+maven.javadoc.doclet            = [${maven.javadoc.doclet}]
+maven.javadoc.docletpath        = [${maven.javadoc.docletpath}]
+maven.javadoc.links             = [${maven.javadoc.links}]
+maven.javadoc.locale            = [${maven.javadoc.locale}]
+maven.javadoc.maxmemory         = [${maven.javadoc.maxmemory}]
+maven.javadoc.mode.online       = [${maven.javadoc.mode.online}]
+maven.javadoc.offlineLinks      = [${maven.javadoc.offlineLinks}]
+maven.javadoc.overview          = [${maven.javadoc.overview}]
+maven.javadoc.package           = [${maven.javadoc.package}]
+maven.javadoc.private           = [${maven.javadoc.private}]
+maven.javadoc.public            = [${maven.javadoc.public}]
+maven.javadoc.source            = [${maven.javadoc.source}]
+maven.javadoc.stylesheet        = [${maven.javadoc.stylesheet}]
+maven.javadoc.tagletpath        = [${maven.javadoc.tagletpath}]
+maven.javadoc.taglets           = [${maven.javadoc.taglets}]
+maven.javadoc.use               = [${maven.javadoc.use}]
+maven.javadoc.useexternalfile   = [${maven.javadoc.useexternalfile}]
+maven.javadoc.version           = [${maven.javadoc.version}]
+maven.javadoc.windowtitle       = [${maven.javadoc.windowtitle}]
+==================================
+=== javadoc internal variables ===
+==================================
+internal.javadoc.jar            = [${internal.javadoc.jar}]
+internal.javadoc.needed         = [${internal.javadoc.needed}]
+internal.javadoc.src.modifs     = [${internal.javadoc.src.modifs}]
+internal.javadoc.src.set        = [${internal.javadoc.src.set}]
+internal.javadoc.working.dir    = [${internal.javadoc.working.dir}]
+      </ant:echo>
+    </j:if>
+    <j:if test="not ${maven.javadoc.debug}">
+      <ant:echo>
+### Debug mode is off ###
+      </ant:echo>
+    </j:if>
+
+  </goal>
+
+  <!-- ================================================================== -->
+  <!-- Test if we need to call javadoc                                    -->
+  <!-- ================================================================== -->
+
+  <define:taglib uri="javadoc">
+    <define:tag name="check-needed">
+      <j:if test="${maven.javadoc.debug}"><ant:echo>check-needed</ant:echo></j:if>
+      <j:choose>
+      
+        <j:when test="${internal.javadoc.needed != null}">
+          <!-- We have already decided if javadoc is needed -->
+          <j:if test="${maven.javadoc.debug}"><ant:echo>${internal.javadoc.needed} not null</ant:echo></j:if>
+        </j:when>
+                
+        <j:otherwise>
+          <!-- Create a patternset for source modifications -->
+          <patternset id="source.modifications">
+            <ant:include name="**/*.java"/>
+            <!-- handle source modifications -->
+            <j:forEach var="sm" items="${pom.build.sourceModifications}">
+              <ant:available property="classPresent" classname="${sm.className}"/>
+              <j:if test="${classPresent != 'true'}">
+                <j:forEach var="exclude" items="${sm.excludes}">
+                  <ant:exclude name="${exclude}"/>
+                </j:forEach> <!-- end sourceModification exclude -->
+                <j:forEach var="include" items="${sm.includes}">
+                  <ant:include name="${include}"/>
+                </j:forEach> <!-- end sourceModification include -->
+              </j:if>
+            </j:forEach> <!-- end sourceModification -->
+          </patternset>
+          
+          <!-- test if sourceModifications are defined -->
+          <j:if test="${pom.build.sourceModifications != null &amp;&amp; !pom.build.sourceModifications.isEmpty()}">
+            <j:set var="internal.javadoc.src.modifs" scope="parent" value="true"/>
+          </j:if>
+          
+          <j:if test="${maven.javadoc.debug}">
+            <ant:echo>internal.javadoc.src.modifs is ${internal.javadoc.src.modifs}</ant:echo>
+          </j:if>
+
+          <!-- Tokenize the set of directories -->
+          <util:tokenize var="sources.dirs" delim="${path.separator}">${internal.javadoc.src.set}</util:tokenize>
+          
+          <!-- Counter used to name filesets -->
+          <j:set var="src.set.counter" value="0"/>
+          
+          <!-- For each directory -->
+          <j:forEach var="dir" items="${sources.dirs}">
+            <!-- If we have not already find sources -->
+            <j:if test="${internal.javadoc.needed != true}">
+              <!-- We construct the fileset -->
+              <ant:fileset id="${src.set.counter}" dir="${dir}">
+                <patternset refid="source.modifications"/>
+              </ant:fileset> 
+  
+              <ant:fileScanner var="sources">
+                <ant:fileset refid="${src.set.counter}" />
+              </ant:fileScanner>
+    
+              <j:set var="internal.javadoc.needed" scope="parent" 
+                 value="${sources.iterator().hasNext()}" />
+  
+              <j:set var="src.set.counter" value="${src.set.counter + 1}"/>
+            </j:if>
+          </j:forEach> <!-- dir in maven.compile.src.set -->
+
+        </j:otherwise>
+      </j:choose>
+
+      <j:if test="${maven.javadoc.debug}">
+        <ant:echo>internal.javadoc.needed is ${internal.javadoc.needed}</ant:echo>
+      </j:if>
+
+    </define:tag>
+  </define:taglib>
+
+
+  <!-- ================================================================== -->
+  <!-- J A V A D O C S   R E P O R T S                                    -->
+  <!-- ================================================================== -->
+
   <goal name="maven-javadoc-plugin:register">      
 
     <javadoc:check-needed/>
 
-    <j:if test="${needed}">
+    <j:if test="${internal.javadoc.needed}">
       <doc:registerReport 
         name="JavaDocs" 
         pluginName="maven-javadoc-plugin"
@@ -54,88 +222,17 @@
     <doc:deregisterReport name="JavaDoc Report"/>
   </goal>
 
-  <!-- ================================================================== -->
-  <!-- Test if we need to call javadoc                                    -->
-  <!-- ================================================================== -->
-
-  <define:taglib uri="javadoc">
-    <define:tag name="check-needed">
-      
-      <j:choose>
-      
-        <j:when test="${needed != null}">
-          <!-- We have already decided if javadoc is needed -->
-        </j:when>
-        
-        <j:when test="${sourcesPresent != 'true'}">
-          <j:set var="needed" value="false" />
-        </j:when>
-        
-        <j:otherwise>
-          <!-- Create a patternset for source modifications -->
-          <patternset id="source.modifications">
-            <ant:include name="**/*.java"/>
-            <!-- handle source modifications -->
-            <j:forEach var="sm" items="${pom.build.sourceModifications}">
-              <ant:available property="classPresent" classname="${sm.className}"/>
-              <j:if test="${classPresent != 'true'}">
-                <j:forEach var="exclude" items="${sm.excludes}">
-                  <ant:exclude name="${exclude}"/>
-                </j:forEach> <!-- end sourceModification exclude -->
-                <j:forEach var="include" items="${sm.includes}">
-                  <ant:include name="${include}"/>
-                </j:forEach> <!-- end sourceModification include -->
-              </j:if>
-            </j:forEach> <!-- end sourceModification -->
-          </patternset>
-
-          <!-- Tokenize the set of directories -->
-          <util:tokenize var="sources.dirs" delim="${path.separator}">${context.getAntProject().getReferences().get('maven.compile.src.set')}</util:tokenize>
-          
-          <!-- Counter used to name filesets -->
-          <j:set var="src.set.counter" value="0"/>
-          
-          <!-- For each directory -->
-          <j:forEach var="dir" items="${sources.dirs}">
-            <!-- If we have not already find sources -->
-            <j:if test="${needed != true}">
-              <!-- We construct the fileset -->
-              <ant:fileset id="${src.set.counter}" dir="${dir}">
-                <patternset refid="source.modifications"/>
-              </ant:fileset> 
-  
-              <ant:fileScanner var="sources">
-                <ant:fileset refid="${src.set.counter}" />
-              </ant:fileScanner>
-    
-              <j:set var="needed" scope="parent" 
-                 value="${sources.iterator().hasNext()}" />
-  
-              <j:set var="src.set.counter" value="${src.set.counter + 1}"/>
-            </j:if>
-          </j:forEach> <!-- dir in maven.compile.src.set -->
-
-        </j:otherwise>
-      </j:choose>
-
-    </define:tag>
-  </define:taglib>
-
   <!-- ================================================================== -->
   <!-- J A V A D O C S                                                    -->
   <!-- ================================================================== -->
 
-  <!-- Some aliases for ease of use and backward compat. -->
-  <goal name="javadoc:generate" prereqs="maven-javadoc-plugin:report"/>
-  <goal name="javadoc" prereqs="maven-javadoc-plugin:report"/>
-
   <goal name="maven-javadoc-plugin:report"
-        prereqs="xdoc:init"
+        prereqs="javadoc:init"
         description="Generate API documentation">
 
     <javadoc:check-needed/>
     
-    <j:if test="${needed}">
+    <j:if test="${internal.javadoc.needed}">
 
       <ant:mkdir dir="${maven.javadoc.destdir}"/>
 
@@ -180,8 +277,8 @@
 
       <j:set var="maxMemory" value="${maven.javadoc.maxmemory}" />
 
-      <ant:mkdir dir="${maven.build.dir}/javadoc/" />
-      <ant:record name="${maven.build.dir}/javadoc/report.txt" action="start" />
+      <ant:mkdir dir="${internal.javadoc.working.dir}" />
+      <ant:record name="${internal.javadoc.working.dir}/report.txt" action="start" />
       
       <ant:javadoc
         packagenames="${pom.package}.*"
@@ -198,20 +295,35 @@
         stylesheetfile="${maven.javadoc.stylesheet}"
         additionalparam="${maven.javadoc.additionalparam}"
         useexternalfile="${maven.javadoc.useexternalfile}"
+        verbose="${maven.javadoc.debug}"
         >
 
-        <!-- Tokenize the set of directories -->
-        <util:tokenize var="sources.dirs" delim="${path.separator}">${context.getAntProject().getReferences().get('maven.compile.src.set')}</util:tokenize>
-    
-        <j:forEach var="dir" items="${sources.dirs}">
+        <j:if test="${internal.javadoc.src.modifs == true}">
+          <j:if test="${maven.javadoc.debug}">
+            <ant:echo>Javadoc uses a fileset</ant:echo>
+          </j:if>
+          <!-- Tokenize the set of directories -->
+          <util:tokenize var="sources.dirs" delim="${path.separator}">${internal.javadoc.src.set}</util:tokenize>
+      
+          <j:forEach var="dir" items="${sources.dirs}">
+          
+            <echo>[${dir}] added to javadoc sources</echo>
+            <ant:fileset dir="${dir}">
+              <patternset refid="source.modifications"/>
+            </ant:fileset> 
+  
+          </j:forEach> <!-- dir in maven.compile.src.set -->        
+        </j:if>
+
+        <j:if test="${internal.javadoc.src.modifs != true}">
+          <j:if test="${maven.javadoc.debug}">
+            <ant:echo>Javadoc uses a source path</ant:echo>
+          </j:if>
+          <ant:sourcepath>
+            <ant:path refid="maven.compile.src.set"/>
+          </ant:sourcepath>
+        </j:if>
         
-          <echo>[${dir}] added to javadoc sources</echo>
-          <ant:fileset dir="${dir}">
-            <patternset refid="source.modifications"/>
-          </ant:fileset> 
-
-        </j:forEach> <!-- dir in maven.compile.src.set -->        
-
         <j:if test="${context.getVariable('maven.javadoc.source') != null}">
           <ant:setProperty name="source" value="${maven.javadoc.source}" />
         </j:if>
@@ -298,12 +410,12 @@
 
       </ant:javadoc>
       
-      <ant:record name="${maven.build.dir}/javadoc/report.txt" action="stop" />
+      <ant:record name="${internal.javadoc.working.dir}/report.txt" action="stop" />
 
       <j:set var="genDocs" value="${maven.gen.docs}" />
       
       <!-- load file in order to remove absolute paths -->
-      <util:file name="${maven.build.dir}/javadoc/report.txt" var="inputFileObject"/>
+      <util:file name="${internal.javadoc.working.dir}/report.txt" var="inputFileObject"/>
       <util:loadText var="inputText" file="${inputFileObject}"/>
     
       <!-- remove [javadoc] prefix from rows -->
@@ -334,34 +446,40 @@
         section="Javadoc Report"
         inputText="${inputText}"
         output="${genDocs}/javadoc.xml"/>
-        
-      <!-- 
-      Because we use in the javadoc task a fileset and not a packageset
-      (to allow sourceModifications) the javadoc doesn't copy 
-      automatically doc-files directories.
-      We must do it manually.
-      -->
-      <util:tokenize var="sources.dirs" delim="${path.separator}">${context.getAntProject().getReferences().get('maven.compile.src.set')}</util:tokenize>
-      <ant:copy todir="${maven.javadoc.destdir}">
-        <j:forEach var="dir" items="${sources.dirs}">      
-          <ant:fileset dir="${dir}">
-            <ant:include name="**/doc-files/**/*"/>
-          </ant:fileset>
-        </j:forEach>
-      </ant:copy>
+      
+      <j:if test="${internal.javadoc.src.modifs}">  
+        <!-- 
+        Because we use in the javadoc task a fileset and not a packageset
+        (to allow sourceModifications) the javadoc doesn't copy 
+        automatically doc-files directories.
+        We must do it manually.
+        -->
+        <util:tokenize var="sources.dirs" delim="${path.separator}">${internal.javadoc.src.set}</util:tokenize>
+        <ant:copy todir="${maven.javadoc.destdir}">
+          <j:forEach var="dir" items="${sources.dirs}">      
+            <ant:fileset dir="${dir}">
+              <ant:include name="**/doc-files/**/*"/>
+            </ant:fileset>
+          </j:forEach>
+        </ant:copy>
+      </j:if>
     </j:if>
 
-    <j:if test="${!needed}">
+    <j:if test="not ${internal.javadoc.needed}">
       <ant:echo>No sources found. Javadoc not created !</ant:echo>
     </j:if>
   </goal>
+
+  <!-- ================================================================== -->
+  <!-- P A C K A G E  A N D  D E P L O Y  J A V A D O C S                 -->
+  <!-- ================================================================== -->
   
   <!--==================================================================-->
   <!-- Create a jar file containing the javadoc                         -->
   <!--==================================================================-->      
   <goal name="javadoc:jar" prereqs="javadoc">
     <j:set var="maven.javadoc.final.name" 
-           value="${maven.build.dir}/${maven.final.name}_javadoc.jar" />   
+           value="${internal.javadoc.jar}" />   
     <ant:jar 
          destfile="${maven.javadoc.final.name}"
          basedir="${maven.javadoc.destdir}"         
@@ -424,4 +542,13 @@
         project="${pom}"/>    
         
   </goal>
+
+  <!-- ================================================================== -->
+  <!-- B A C K W A R D  C O M P A T I B I L I T Y                         -->
+  <!-- ================================================================== -->
+
+  <!-- Some aliases for ease of use and backward compat. -->
+  <goal name="javadoc:generate" prereqs="maven-javadoc-plugin:report"/> 
+  <goal name="javadoc" prereqs="maven-javadoc-plugin:report"/>
+
 </project>
diff --git a/javadoc/xdocs/changes.xml b/javadoc/xdocs/changes.xml
index 8e807234..af2b2749 100644
--- a/javadoc/xdocs/changes.xml
+++ b/javadoc/xdocs/changes.xml
@@ -24,6 +24,9 @@
   </properties>
   <body>
     <release version="1.5.1-SNAPSHOT" date="In CVS">
+      <action dev="aheritier" type="fix" issue="MPJAVADOC-29">Packages list broken on jdk 1.3 for multiple packages.</action>
+      <action dev="aheritier" type="fix" issue="MPJAVADOC-28">@link tag not working with package names.</action>
+      <action dev="aheritier" type="add">Add the property maven.javadoc.debug to print informations to debug the plugin.</action>
       <action dev="aheritier" type="fix" issue="MPJAVADOC-26" due-to="Denis McLaughlin">Fix the needed flag when there's an empty sources directory.</action>
       <action dev="aheritier" type="fix" issue="MPJAVADOC-24">doc-files directories contents are correctly copied.</action>
       <action dev="brett" type="fix" issue="MPJAVADOC-5">Add support for multiple source directories.</action>
diff --git a/javadoc/xdocs/properties.xml b/javadoc/xdocs/properties.xml
index d537a30e..48e1e059 100644
--- a/javadoc/xdocs/properties.xml
+++ b/javadoc/xdocs/properties.xml
@@ -73,6 +73,14 @@ tag2.scope=all
             ]]></source>
           </td>
         </tr>
+        <tr>
+          <td>maven.javadoc.debug</td>
+          <td>Yes</td>
+          <td>
+            Print informations to debug the plugin. 
+            The default value is <code>false</code>.
+          </td>
+        </tr>
         <tr>
           <td>maven.javadoc.destdir</td>
           <td>Yes</td>