Ant: The Definitive Guide

Documenting the Buildfile’s Targets

Q: We have a complex buildfile. When new developers join the project, the learning curve on how to use the buildfile is high. We feel like we waste a lot of time teaching what the buildfiles do instead of better integrating the new employee with the team. We’ve placed some documentation on an intranet site, and this helps, but, as we all know, not everyone reads the documentation. What else can we do?

Don’t ignore the description attribute for targets. Being able to run Ant with the -projecthelp option and get detailed feedback is another way to shorten developers’ ramp-up time on a project and increase productivity.

For example, the following target uses the description attribute to include some documentation:

<target name="do-something-really-complex" 
          depends="less-complex-stuff"
          description="Perform a lot of checks and tests so you know your project 
works right.  You wouldn't know this target did this unless we provided a 
decription.  It's good that you know now, eh?">
...
</target>

Of course, there’s a chance to go overboard here. Describe only the targets you want executed from the command line. While -projecthelp will list all targets, it separates the list into those with descriptions and those without. Most developers pick up on this quickly and know to avoid running the descriptionless targets. If you really do want to document targets that shouldn’t run from the command line, include a message such as the following in those target descriptions: ...