ant-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bill Rich" <billr...@attglobal.net>
Subject RE: show list of available tasks
Date Sat, 13 Mar 2004 17:00:12 GMT
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


Mime
View raw message