File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Ant, Maven and Other Build Tools and the fly likes [ant] javadoc task Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of EJB 3 in Action this week in the EJB and other Java EE Technologies forum!
JavaRanch » Java Forums » Engineering » Ant, Maven and Other Build Tools
Bookmark "[ant] javadoc task" Watch "[ant] javadoc task" New topic
Author

[ant] javadoc task

Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
Could somebody please post an example of their javadoc task?
I'm doing something wrong that's probably intuitively obvious to the most casual observer but I'm missing something with my Ant inexperience. Do I need the classpath in my javadoc task?
Here's what I'm trying to do:

Here's the error message I get:

Thanks in advance for any clues -
Greg


Greg Ostravich - SCPJ2
Guy Allard
Ranch Hand

Joined: Nov 24, 2000
Posts: 776
Greg - Not sure about your particular problem.
I use the 'classpathref' and 'sourcepathref' attributes of the 'javadoc' tag.
There are a number of working build.xml files on sourceforge or other open source sites.
Here is one:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/joda/Joda/build.xml?rev=1.10&content-type=text/vnd.viewcvs-markup
HTH, Guy
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
Thanks for the great link. I looked at the build on sourceforge and it has lots of stuff in it.
My example still isn't working though.
It seems like it's all related to the packagenames attribute.
My build is producing a JAR that is my application. I don't name my jar with a package name like 'org.joda.*' or 'com.blah.*'.
Do I need to do this?
If so, how do I pick a name?
Before I was using Ant, I created javadoc with the javadoc command and had run it from a bat file. I didn't need to specify any package information.
All the examples I have found use the packagenames attribute.
Any more clues?
Thanks for the help so far.
[ August 13, 2002: Message edited by: Greg Ostravich ]
Guy Allard
Ranch Hand

Joined: Nov 24, 2000
Posts: 776
If I understand you, all your sources and class files are in the current working directory and all classes are in the
'default' package.
If so, try:

I do not guarantee that will work!
With Ant, a lot of times you just need to experiment with different options (and read the docs of course).
Guy
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
Guy -
Thanks for all your help. Ant is great but it seems like it's similar to other things (EJB Deployment, Web Server Config, etc.) that once you have it work you're all set. Getting it configured right can be a bear for some features.
I made some progress but am not where I want to be. I took a stripped down xml file with just the build for makedoc and copied it to my source directory using "." for the sourcepathref. When I use the build you showed me it ran javadoc. When I use my big build (back in my root directory) it still is having problems.
I am using the default package for my app but I have a source tree built within my 'build' directory. This is so I can apply filters during my copy task to copy my source from my SourceSafe managed directory to my build area. Then I compile from my build source tree.
The wierd thing is that it seems like the error message I get is from the javadoc application. Does that mean the javadoc task is not passing in my package name or that it always passes a package name to javadoc even if I don't use the package switch when I normally run it from the command line?
Here's what I currently have:

Thanks again for your help.
[ August 14, 2002: Message edited by: Greg Ostravich ]
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
I went to our Denver Java User Group last night and we were fortunate enough to have James Duncan Davidson there last night as our main speaker.
I asked him about this particular issue and he said Ant was always buggy about this. I will as a future endeavor try either looking at the source for the Javadoc task and/or rename my project to be a package so everything can resolve.
Thanks for all your help -
BTW: Very interesting history and trivia last night. James Duncan Davidson talked about the history of Tomcat, Ant, and moving those projects to Apache.
The reason it is called Jakarta is that is the name of the conference room that they first met in to discuss it.
He picked Tomcat as the name because he was thinking about the O'Reilly books and the animals on the cover and what animal he wanted. The whole politics about his push to get Tomcat under Apache and getting the upper management at Sun to say OK was interesting too.
He talked about the biggest challenge was addressing legal issues in moving Tomcat from Sun to a non-profit. The lawyers weren't use to that model. He talked about slipping Ant in to the Tomcat release and his surprise at how well it caught on. He said he's looking for an Ant killer - the next great thing that'll be better than Ant.
Thomas Paul
mister krabs
Ranch Hand

Joined: May 05, 2000
Posts: 13974
I wrote an article on Ant for the JavaRanch newsletter. I think it was published in March. I have an example of using JavaDoc so maybe it will help. (The link to the newsletters can be found on the front page of JavaRanch.)


Associate Instructor - Hofstra University
Amazon Top 750 reviewer - Blog - Unresolved References - Book Review Blog
Matthew Phillips
Ranch Hand

Joined: Mar 09, 2001
Posts: 2676
Or you can just click here.


Matthew Phillips
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
Thanks for the link. The newletter article you wrote looks great. Unfortunately it won't help my situation.
Javadoc can be run from the command line by just specifying a wildcard for the source files and the destination directory.
For example:

The problem is that since the project I'm working on isn't in a package directory my Javadoc task fails in Ant. If you look at the source code in the Javadoc task, it specifically checks for either the sourcefiles or the packagename. It needs one of the two to run - even though Javadoc can run from the command line with a wildcard to specify the file list and without specifying a package name.
Here's the code form Javadoc.java:

If my project was set-up in a package directory structure I suspect it would have worked but it's not.
So either I'll attempt to change the javadoc task code to run without specifying files explicitly, or I'll change my project to use a packagename and file structure.
James said last night that if you use the sourcefiles command you have to specify each filename and I don't want to do that either.
If you've made it work by somehow specifying a wildcard for sourcefiles please let me know - I'd love to make that work. When I try it I get a message that the file in question (*.java for example)cannot be found.
[ August 15, 2002: Message edited by: Greg Ostravich ]
Thomas Paul
mister krabs
Ranch Hand

Joined: May 05, 2000
Posts: 13974
You should always keep your project in the package structure because the change dependent compile won't work otherwise. You'll end up always re-compiling everything.
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
OK, I'll byte (pun intended).
I do plan on implementing my projects in the package structure from now on (because of the headaches I ran into like this one) and because it's a 'better' way to do it.
That said - why does it matter if my source tree looked like the package structure for file dependencies?
I did look and you're right -- if I do an Ant compile it looks like it recompiles my code everytime.
My existing project has a source tree (./src/main and ./src/test) that is copied to a build/src staging area (so I can use a filter task on my source code) and in the build area I compile into build/lib, build/classes.
So why is that?
[ August 15, 2002: Message edited by: Greg Ostravich ]
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
Update:
I've changed my app to be a package and the good news is everything's happy for my application's javadoc. The bad news is it complains on my unit tests. Both my Unit tests and my application are in the same package (different directory though). I had to mess with my build to make my unit tests work again. If somebody has any suggestions on how to fix the javadoc for my unit tests I'll take a stab at it, otherwise I think I'm done messing with the javadoc and junit portions of my build file.
If you're interested - here's the details.
If not, thanks for your help - I'm glad I got the javadoc to generate.
Here's the javadoc target for my unit test api:

Here's my error messages:
maketestdoc:

[ August 16, 2002: Message edited by: Greg Ostravich ]
Guy Allard
Ranch Hand

Joined: Nov 24, 2000
Posts: 776
Couple of possibilities:
1) junit.jar is not in CLASSPATH when javadoc is run. Make sure that it is.
and/or
2) You may need to change packagenames= from
...junit.framework
to
...junit.framework.*

Guy
[ August 17, 2002: Message edited by: Guy Allard ]
Thomas Paul
mister krabs
Ranch Hand

Joined: May 05, 2000
Posts: 13974
Originally posted by Greg Ostravich:
That said - why does it matter if my source tree looked like the package structure for file dependencies?
Ant does a compare of filenames not package names. It doesn't look into the source file to determine if it should be compiled. It only looks at the source file name. So if the source file name is MyCode.java, it has no idea that MyCode.java is part of MyPackage.MyJava and can't find the compiled class file.
Greg Ostravich
Ranch Hand

Joined: Jul 11, 2002
Posts: 112
Thanks Guy!
That worked.
I added both the import junit.framework.* and modified my classpath to add JUnit.jar for the javadoc command and it works great.
I'm very excited that I've accomplished almost all of my goals for my build file.
I now can generate all my documentation and run my unit tests from my build. I generate HTML for my Unit Test results. During my build I set a DEBUG flag on the command line to true or false and that effects how I compile my DEBUG class to be turned off or on using the filter task.
The only thing more I want to do is to e-mail my results after the unit test and to have my DEBUG flag be optional - if it's not passed it sets DEBUG to false, if it is passed it sets DEBUG to the value passed.
I know the e-mail thing should be simple and I've got some examples somewhere - and then the only trick will be the conditional if my command line option isn't passed.
I just wanted to say thank you for everybody's help! I'm so exited about how well my build is working.
Jie Li
Greenhorn

Joined: May 14, 2003
Posts: 1
I still get no package or class error.
Please help!

my java file d:\tmp\src\test.java
==============
package framework.util;
my build.xml
=================
<target name="api"
description="Generate API documentation">
<javadoc sourcepath="${src}"
destdir="${api}"
packagenames="framework.util.*"/>
</target>
run ant
===========
ant -buildfile build.xml
The error message:
file :/tmp/build.xml:34: No source files and no packages have been specified.
Greg Charles
Sheriff

Joined: Oct 01, 2001
Posts: 2771
    
  10

Welcome to Java Ranch! You would probably do better to start a new thread for new questions. Fortunately, I read to the bottom of this one.
Unfortunately, I don't have answers, just more questions. What is the src variable defined to be? Are there actually source files in that directory? Do they follow the package hierarchy?
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: [ant] javadoc task
 
Similar Threads
Ant X JavaDoc
Ant X JavaDoc
Trying to invoke javadoc tag within Ant problem.
"Could not create task of type: echo"
ant wsdl2java: classpath error