I think that ant did what it should have done. The <description> tag is for use on the
<project> level not the <target> level. Ant found the project description and
put it out
where it should. Target descriptions are an attribute of the <target> tag.
I think this comes down to a philosophy of how to write documentation and how it will be
used. If the target description is intended to be the full documentation of what the
target does and how to use it then there are many other ways to implement it. If the
target description is intended to be a reminder as to what the task does then it is very
useful now. As a general rule (and sometimes required by contract) I document all my code
in enough detail that another programmer can understand what I intended the code to do
when I am not there to explain it. The bulk of this documentation is contained in
comments with only the external view of the code exposed in "documentation" outside the
code.
IMHO - I use TextPad as my editor-of-choice. It allows me to wrap lines on the screen and
save them without hard returns. This seems to give me the best flexibility for writing
code files. It allows me to resize the display window as needed and still see all the
text for all the lines. I can also turn the wrap off when needed. I know there are many
arguments that say I should be the one who decides where to break a line and that I should
put in all the appropriate breaks so the lines are displayable with any old editor but my
time is worth something and I will tend to use the best tools I can for the job and let
the computer do the more mundane work.
If any changes are made to the documentation features in ant, I would like to see a more
JavaDoc like form where I can put HTML tags in the description for formatting and the
output would be to an HTML file. My whims not withstanding, I find the documentation
feature useful as is and was surprised that ant even had it at so early a release in its
life-cycle.
For my most recent ant script documentation I used the -p -v flags to display the
documentation redirected to a file. I have now added the appropriate HTML tags to that
file and saved it as HTML so I have this information available online. I will now add
more detailed descriptions to the HTML file for the final pass at the documentation for
the ant script. This is not a build application of ant so it needs more documentation.
It will be used by L10N engineers to control at set of tools so it needs more "what is
this for" kinds of explanations than a normal build script.
Before closing - thanks to all the ant contributors for their efforts in bringing ant and
ant-contrib to their current states and for their continued efforts in improving and
extending them. The ant documentation is good and the code generally does what it is
advertised to do. It takes a mind-set change to use ant effectively which is the hardest
part of getting started in using ant, but once you shift into that mind-set things become
clearer. I don't know how to document the mind-set change any better than it is already.
Thank you all very much.
Bill Rich
Wilandra Consulting LLC
1325 Addiewell Place
San Jose, CA 95120-3905
phone: +1 408 268-2452
mobile: +1 408 410-9713
Santa Cruz: +1 831 464-9007
fax: +1 413 669-9716
billrich@wilandra.com or billrich@attglobal.net
http://www.wilandra.com
-----Original Message-----
From: Adam Hardy [mailto:adam.ant@cyberspaceroad.com]
Sent: Saturday, March 13, 2004 2:03 AM
To: user@ant.apache.org
Subject: Re: show list of available tasks
> --- Bill Rich <billrich@attglobal.net> wrote:
>>I think -p -v will yield a list of Major Tasks
>>(those tasks with a description) and Other
>>Tasks (those without a description).
There is another issue - perhaps an enhancement :) - to do with this
subject:
ant -p only picks up the description attribute on the target.
<target name="init" depends="init-common"
description="Sets up the appserver properties and classpath">
</target>
When I was documenting my build file, like the good developer I am, my
descriptions were always a little bit too verbose for one line, and my
editor keeps wanting to wrap them, which is of course not XML.
So I tried this:
<target name="init" depends="init-common">
<description>
Sets up the appserver properties and classpath
and have more than one line bla bla bla
</description>
</target>
and weird things happened. Ant -p missed it, and thought it must be a
private target. But ant didn't miss it entirely, it spat out the
description text at a random place in the output:
Buildfile: build.xml
Sets up the appserver properties and classpath
Main targets:
all Clean build and dist, then compile and deploy war
assemble-ear package all required Jars into EAR
clean delete old build and dist directories
compile Compile Java sources
del-deploy del deployed app from server
del-deploy-tomcat-5 Delete tomcat-5 works deploy dir & context.xml
deploy-ear deploys an EAR file to appserver
deploy-war deploy app to server (or lib if no appserver)
deploy-web deploy app to server (or lib if no appserver)
deploy-web-tomcat-5 places context.xml in conf/Catalina/localhost/
ejb-jar package class files into Jars
init-common Sets up the appserver properties and classpath
jar jars up whatever it finds in build
javadoc Create Javadoc API documentation
war Create war file
Default target: deploy
Bug, enhancement or other?
Adam
--
ant 1.6.0 + java 1.4.2 on Linux 2.4.20 Debian
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: user-unsubscribe@ant.apache.org
For additional commands, e-mail: user-help@ant.apache.org
|