ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ehatc...@apache.org
Subject cvs commit: ant/src/main/org/apache/tools/ant/taskdefs Javadoc.java
Date Wed, 05 Mar 2003 03:03:11 GMT
ehatcher    2003/03/04 19:03:11

  Modified:    .        WHATSNEW
               docs/manual/CoreTasks javadoc.html
               src/main/org/apache/tools/ant/taskdefs Javadoc.java
  Log:
  #17142 - enhance Javadoc tag element to allow a fileset
  
  Revision  Changes    Path
  1.359     +3 -0      ant/WHATSNEW
  
  Index: WHATSNEW
  ===================================================================
  RCS file: /home/cvs/ant/WHATSNEW,v
  retrieving revision 1.358
  retrieving revision 1.359
  diff -u -r1.358 -r1.359
  --- WHATSNEW	24 Feb 2003 08:25:18 -0000	1.358
  +++ WHATSNEW	5 Mar 2003 03:03:11 -0000	1.359
  @@ -234,6 +234,9 @@
     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
   ====================================
   
  
  
  
  1.23      +46 -29    ant/docs/manual/CoreTasks/javadoc.html
  
  Index: javadoc.html
  ===================================================================
  RCS file: /home/cvs/ant/docs/manual/CoreTasks/javadoc.html,v
  retrieving revision 1.22
  retrieving revision 1.23
  diff -u -r1.22 -r1.23
  --- javadoc.html	8 Nov 2002 16:10:12 -0000	1.22
  +++ javadoc.html	5 Mar 2003 03:03:11 -0000	1.23
  @@ -22,16 +22,16 @@
   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 @@
       <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 @@
     </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 @@
       <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 @@
   <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 @@
     &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 @@
     <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 @@
     <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 @@
     </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 @@
       &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 @@
     &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 @@
     &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>
  
  
  
  1.109     +30 -4     ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
  
  Index: Javadoc.java
  ===================================================================
  RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java,v
  retrieving revision 1.108
  retrieving revision 1.109
  diff -u -r1.108 -r1.109
  --- Javadoc.java	19 Feb 2003 12:30:55 -0000	1.108
  +++ Javadoc.java	5 Mar 2003 03:03:11 -0000	1.109
  @@ -58,6 +58,8 @@
   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 @@
       /**
        * 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 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 @@
                       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");
  
  
  

Mime
View raw message