After a svn checkout of:

  http://svn.apache.org/repos/asf/tomcat/tc6.0.x/tags/TOMCAT_6_0_16

and a successful build I tried following the instruction in BUILDING.txt for generating the javadoc however running:

  ant -f dist.xml dist-javadoc

produced this error:

BUILD FAILED
/Users/stephen/dev/java/src/tomcat_6_0_16/dist.xml:368: No source files and no packages have been specified.

I needed to run this first to produce the documentation:

  ant -f dist.xml dist-source

You could either add a statement about this to this section of the instructions in: BUILDING.txt

(5) Building the servlet and jsp API documentation

The documentation can be easly built:

    cd ${tomcat.source}
    ant -f dist.xml dist-javadoc

Or apply this patch which adds dist-source as a dependency to the dist-javadoc ant task:

Index: dist.xml
===================================================================
--- dist.xml	(revision 645027)
+++ dist.xml	(working copy)
@@ -356,7 +356,7 @@
 
   </target>
 
-  <target name="dist-javadoc" description="Create the Tomcat javadoc" >
+  <target name="dist-javadoc" depends="dist-source" description="Create the Tomcat javadoc" >
     <javadoc packagenames="org.apache.*"
       sourcepath="${tomcat.dist}/src/java"
       destdir="${tomcat.dist}/webapps/docs/api"


fyI: regarding OS: I'm running MacOS 10.5.2 -- Mac OS X 10.5 should be added to your bugzilla list of OS types.