ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chane...@netscape.com (Patrick Chanezon)
Subject Re: [PATCH]: enhanced javadoc task
Date Tue, 21 Mar 2000 00:19:20 GMT
Sorry to get back on this so late.

Thanks for the comments on the patch.
I agree with the syntax remark: it is much more elegant if the synatx for multiple lines is
all XML and I'll try to
implement it.

My ";" notation was a quick fix that I needed to get it to run. I implemented it that way
because I did not have time to
investigate why the XML parser broke when I added multiple link tags.

As of the @filename option, it is just an extension and you are not obliged to use it, but
I find it handy to have for
projects which have an existing packagelist files and want to migrate quickly.
Moreover, the packagelist is not checked, so the task performs even if some packages are missing
or broken. So I found it
more practical to use on my current project where a lot of packages are broken.
The use case for it would be:
It as an option to use to get things running, and switch to the regular notation when your
project is in a more stable
state.
A last argument is: why would you forbid an argument of javadoc if it exists in the command
line. If you don't like it,
don't use it, but at least it is there if you want.

Do you really want it out ?

P@

Stefano Mazzocchi wrote:

> Patrick Chanezon wrote:
> >
> > Hi ant users and developers,
> >
> > I enhanced the javadoc task in order to make full use of some javadoc
> > features as descibed in
> > http://jakarta.apache.org/bugs/show_bug.cgi?id=64
> >
> > which means:
> > * support for multiple link options
> > * support for multiple group options
> > * support for the @ argument
> >
> >  - link and linkoffline: you can now list more than one -link option,
> > using a ; separator in your link tag to separate the different lines
> > that will be generated
> >  - group: same remark, you can now list more than one -group option,
> > using a ; separator in your group tag. arguments are
> > groupheading;packagepattern:packagepattern:..
> >  - group: the syntax is "-group  groupheading
> > packagepattern:packagepattern:.."
> >  - the COMMAND LINE ARGUMENT FILE syntax: javadoc -d apidocs @packages
> > is now supported with the packagelist
> > tag this is how these options can be used in a build.xml file:
> >
> >     <javadoc sourcepath="${src.dir}"
> >              destdir="${build.javadocs}"
> >              author="true"
> >              version="true"
> >              windowtitle="${Name} API"
> >              doctitle="${Name}"
> >              bottom="Copyright &#169; 2000 Apache Software Foundation.
> > All Rights Reserved."
> >
> > link="http://java.sun.com/products/jdk/1.2/docs/api/;http://developer.java.sun.com/developer/products/xml/docs/api/"
> >
> >              group="Ant Tools Packages;org.apache.tools.ant;Ant Task
> > Packages;org.apache.tools.ant.taskdefs"
> >              packageList="src/etc/packagelist.txt"
> >     />
> >
> > I also attach a modified version of build.xml for ant and
> > packagelist.txt (you should put it in src/etc)
> > try ant javadocs on your ant tree with the patch and these 2 files, to
> > see the result.
>
> I don't like this.
>
> The javadoc task was explicitly written to avoid to maintain a separate
> package list or any external file.
>
> > And let me know if you like the separator syntax: allowing 2 attributes
> > with the same name would maybe be a better option, and an xml element
> > for groups, with 2 attributes. It would be more readable. If you prefer
> > this just let me know so that I can implement it.
>
> I'd love to use XML for the whole thing and avoid in-string separator
> syntax.
>
> Something like:
>
>  <javadoc sourcepath="${src.dir}"
>           packages="org.apache.tools.ant.*"
>           destdir="${build.javadocs}"
>           author="true"
>           version="true"
>           windowtitle="${Name} API"
>           doctitle="${Name}"
>           bottom="Copyright &#169; ${year} Apache Software Foundation.">
>    <link href="http://java.sun.com/products/jdk/1.2/docs/api/"/>
>    <link
> href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
>    <group title="Ant Tools Packages" packages="org.apache.tools.ant"/>
>    <group title="Ant Task Packages"
> packages="org.apache.tools.ant.taskdefs"/>
>  </javadoc>
>
> with no external package list.
>
> --
> Stefano Mazzocchi      One must still have chaos in oneself to be
>                           able to give birth to a dancing star.
> <stefano@apache.org>                             Friedrich Nietzsche
> --------------------------------------------------------------------
>  Come to the first official Apache Software Foundation Conference!
> ------------------------- http://ApacheCon.Com ---------------------

--
Patrick Chanezon, Vortex - Portal/EServices Technical Lead
Netscape Communications Corp. - http://people.netscape.com/chanezon/
Opinions are my own.

"Ouais, n'empêche qu'à la retraite de Russie, c'est les mecs qu'étaient à la traîne qu'ont
été repassés..." - Michel
Audiard - Les Tontons Flingueurs


Mime
View raw message