#17142 - enhance Javadoc tag element to allow a fileset

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@274196 13f79535-47bb-0310-9956-ffa450edef68
22 years ago · 96cf0f7848
--- a/+ 3
+++ b/+ 3
@@ -234,6 +234,9 @@ Other changes:
  possible to save the output into a property for use within the build
  file as was possible with <exec> in Ant 1.5

 * The <javadoc> task <tag> subelement has been enhanced to allow files
  with tag mappings to be used.

 Changes from Ant 1.5.1Beta1 to 1.5.1
 ====================================

--- a/docs/manual/CoreTasks/javadoc.html
+++ b/docs/manual/CoreTasks/javadoc.html
@@ -22,16 +22,16 @@ this task is used much less frequently.</p>
 1.2 and 1.4), with the obvious restriction that the 1.2 attributes
 will be ignored if run in a 1.1 VM.</p>
 <p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the
 same VM as ant without breaking functionality. For this reason, this task 
 same VM as ant without breaking functionality. For this reason, this task
 always forks the VM. This overhead is not significant since javadoc is normally a heavy
 application and will be called infrequently.</p>
 <p>NOTE: the packagelist attribute allows you to specify the list of packages to 
 document outside of the Ant file. It's a much better practice to include everything 
 inside the build.xml file. This option was added in order to make it easier to 
 migrate from regular makefiles, where you would use this option of javadoc. 
 The packages listed in packagelist are not checked, so the task performs even 
 if some packages are missing or broken. Use this option if you wish to convert from 
 an existing makefile. Once things are running you should then switch to the regular 
 <p>NOTE: the packagelist attribute allows you to specify the list of packages to
 document outside of the Ant file. It's a much better practice to include everything
 inside the build.xml file. This option was added in order to make it easier to
 migrate from regular makefiles, where you would use this option of javadoc.
 The packages listed in packagelist are not checked, so the task performs even
 if some packages are missing or broken. Use this option if you wish to convert from
 an existing makefile. Once things are running you should then switch to the regular
 notation. </p>

 <p><i><b>DEPRECATION:</b> the javadoc2 task simply points to the javadoc task and it's
@@ -462,7 +462,7 @@ the nested <code>&lt;fileset&gt;</code> elements.</p>
    <td align="center" valign="top">Yes</td>
  </tr>
 </table>
  

 <h4>excludepackage</h4>
 <p>Same as one entry in the list given by <code>excludepackagenames</code>.</p>

@@ -523,7 +523,7 @@ specify multiple occurrences of the arguments.</p>
  </tr>
  <tr>
    <td valign="top">offline</td>
    <td valign="top">True if this link is not available online at the time of 
    <td valign="top">True if this link is not available online at the time of
                     generating the documentation</td>
    <td align="center" valign="top">No</td>
  </tr>
@@ -534,8 +534,8 @@ specify multiple occurrences of the arguments.</p>
    <td align="center" valign="top">Only if the offline attribute is true</td>
  </tr>
 </table>
  
 <h4><a name="groupelement">group</a></h4> 

 <h4><a name="groupelement">group</a></h4>
 <p>Separates packages on the overview page into whatever groups you
 specify, one group per table. This performs the same role as the group
 attribute. You can use either syntax (or both at once), but with the
@@ -566,15 +566,15 @@ with text contents, and the packages may be listed with nested
 <code>&lt;package&gt;</code> elements as for the main task.</p>

 <h4>doclet</h4>
 <p>The doclet nested element is used to specify the doclet that javadoc will 
 <p>The doclet nested element is used to specify the doclet that javadoc will
 use to process the input source files. A number of the standard javadoc arguments
 are actually arguments of the standard doclet. If these are specified in the javadoc
 task's attributes, they will be passed to the doclet specified in the 
 <code>&lt;doclet&gt;</code> nested element. Such attributes should only be specified, 
 task's attributes, they will be passed to the doclet specified in the
 <code>&lt;doclet&gt;</code> nested element. Such attributes should only be specified,
 therefore, if they can be interpreted by the doclet in use.</p>

 <p>If the doclet requires additional parameters, these can be specified with
 <code>&lt;param&gt;</code> elements within the <code>&lt;doclet&gt;</code> 
 <code>&lt;param&gt;</code> elements within the <code>&lt;doclet&gt;</code>
 element. These paramaters are restricted to simple strings. An example usage
 of the doclet element is shown below:</p>

@@ -587,7 +587,7 @@ of the doclet element is shown below:</p>
  &lt;/javadoc&gt;
 </pre>

 <h4><a name="tagelement">tag</a></h4> 
 <h4><a name="tagelement">tag</a></h4>

 <p>The tag nested element is used to specify custom tags. This option
 is only available with Java 1.4.</p>
@@ -602,12 +602,12 @@ is only available with Java 1.4.</p>
  <tr>
    <td valign="top">name</td>
    <td valign="top">Name of the tag (e.g. <code>todo</code>)</td>
    <td align="center" valign="top">Yes</td>
    <td align="center" valign="top">Yes, unless the <code>dir</code> attribute is specified.</td>
  </tr>
  <tr>
    <td valign="top">description</td>
    <td valign="top">Description for tag (e.g. <code>To do:</code>)</td>
    <td align="center" valign="top">Yes</td>
    <td align="center" valign="top">Yes, unless the <code>dir</code> attribute is specified.</td>
  </tr>
  <tr>
    <td valign="top">enabled</td>
@@ -617,15 +617,32 @@ is only available with Java 1.4.</p>
  <tr>
    <td valign="top">scope</td>
    <td valign="top">Scope for the tag - the elements in which it can be used. This
    is a comma separated list of some of the elements: <code>overview</code>, 
    <code>packages</code>, <code>types</code>, <code>constructors</code>, 
    is a comma separated list of some of the elements: <code>overview</code>,
    <code>packages</code>, <code>types</code>, <code>constructors</code>,
    <code>methods</code>, <code>fields</code> or the default, <code>all</code>.</td>
    <td align="center" valign="top">No</td>
  </tr>
  <tr>
    <td valign="top">dir</td>
    <td valign="top">If this attribute is specified, this element will behave as an implicit
    <a href="../CoreTypes/fileset.html">fileset</a>. The files included by this fileset should
    contain each tag definition on a separate line, as described in the
    <a href="http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/javadoc.html#tag">javadoc reference guide</a>:
    <p/>
    <code>
    ejb.bean:t:"XDoclet EJB Tag"<br/>
    todo:a:"To Do"<br/>
    </code>
    <p/>
    Note: If this attribute is specified, all the other attributes in this
    element will be ignored.
    </td>
    <td align="center" valign="top">No</td>
  </tr>
 </table>

 <h4><a name="tagletelement">taglet</a></h4> 
 <p>The taglet nested element is used to specify custom taglets. This option is 
 <h4><a name="tagletelement">taglet</a></h4>
 <p>The taglet nested element is used to specify custom taglets. This option is
 only available with Java 1.4.</p>

 <h5>Parameters</h5>
@@ -637,7 +654,7 @@ only available with Java 1.4.</p>
  </tr>
  <tr>
    <td valign="top">name</td>
    <td valign="top">The name of the taglet class 
    <td valign="top">The name of the taglet class
              (e.g. <code>com.sun.tools.doclets.ToDoTaglet</code>)</td>
    <td align="center" valign="top">Yes</td>
  </tr>
@@ -675,10 +692,10 @@ respectively.</p>
    &lt;link offline=&quot;true&quot; href=&quot;http://java.sun.com/products/jdk/1.2/docs/api/&quot; packagelistLoc=&quot;C:\tmp&quot;/&gt;
    &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
  &lt/javadoc&gt;</pre>
  

 <p>is the same as</p>

 <pre>  &lt;javadoc 
 <pre>  &lt;javadoc
           destdir=&quot;docs/api&quot;
           author=&quot;true&quot;
           version=&quot;true&quot;
@@ -700,8 +717,8 @@ respectively.</p>
  &lt/javadoc&gt;</pre>

 <p>or</p>
  
 <pre>  &lt;javadoc 

 <pre>  &lt;javadoc
           destdir=&quot;docs/api&quot;
           author=&quot;true&quot;
           version=&quot;true&quot;
@@ -723,7 +740,7 @@ respectively.</p>
  &lt/javadoc&gt;</pre>

 <hr>
 <p align="center">Copyright &copy; 2000-2002 Apache Software Foundation. All rights
 <p align="center">Copyright &copy; 2000-2003 Apache Software Foundation. All rights
 Reserved.</p>

 </body>
--- a/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
+++ b/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
@@ -58,6 +58,8 @@ import java.io.FileWriter;
 import java.io.FilenameFilter;
 import java.io.IOException;
 import java.io.PrintWriter;
 import java.io.BufferedReader;
 import java.io.FileReader;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.Enumeration;
@@ -1244,7 +1246,7 @@ public class Javadoc extends Task {
    /**
     * Class representing a -tag argument.
     */
    public class TagArgument {
    public class TagArgument extends FileSet {
        /** Name of the tag. */
        private String name = null;
        /** Description of the tag to place in the JavaDocs. */
@@ -1468,7 +1470,7 @@ public class Javadoc extends Task {
     */
    public void setSource(String source) {
        if (!javadoc4) {
            log ("-source option not supported on JavaDoc < 1.4", 
            log ("-source option not supported on JavaDoc < 1.4",
                 Project.MSG_VERBOSE);
        }
        this.source = source;
@@ -1744,8 +1746,32 @@ public class Javadoc extends Task {
                    Object element = e.nextElement();
                    if (element instanceof TagArgument) {
                        TagArgument ta = (TagArgument) element;
                        toExecute.createArgument().setValue ("-tag");
                        toExecute.createArgument().setValue (ta.getParameter());
                        File tagDir = ta.getDir(getProject());
                        if (tagDir == null ) {
                            // The tag element is not used as a fileset,
                            // but specifies the tag directly.
                            toExecute.createArgument().setValue ("-tag");
                            toExecute.createArgument().setValue (ta.getParameter());
                        } else {
                            // The tag element is used as a fileset. Parse all the files and
                            // create -tag arguments.
                            DirectoryScanner tagDefScanner = ta.getDirectoryScanner(getProject());
                            String[] files = tagDefScanner.getIncludedFiles();
                            for (int i = 0; i < files.length; i++) {
                                File tagDefFile = new File( tagDir, files[i] );
                                try {
                                    BufferedReader in = new BufferedReader( new FileReader(tagDefFile) );
                                    String line = null;
                                    while( (line = in.readLine()) != null ) {
                                        toExecute.createArgument().setValue ("-tag");
                                        toExecute.createArgument().setValue (line);
                                    }
                                    in.close();
                                } catch( IOException ioe ) {
                                    throw new BuildException( "Couldn't read tag file from " + tagDefFile.getAbsolutePath(), ioe );
                                }
                            }
                        }
                    } else {
                        ExtensionInfo tagletInfo = (ExtensionInfo) element;
                        toExecute.createArgument().setValue("-taglet");