Why might javadoc be failing to generate a page for a particular class?

Question

I have a project with a handful of packages and classes in it.

When running javadoc against the project (using Apache ant's task), I believe every class is being documented except for the one I happen to be working on, now.

The class does not appear in the "All Classes" frame. The class does not appear in either of the "Package" frames. There are no files on the disk with the same name as the class (which of course all other classes have).

Some things I've checked:

1. Other classes in the same package are being documented, so this class isn't being "excluded" due to its package.

2. The class is public, so it's not being hidden due to a visibility issue.

3. The source file does in fact contain correct /** javadoc-style comments at the class level as well as for some constructors and member methods.

4. When running javadoc -verbose, I can see the source file is being loaded: [javadoc] [parsing started RegularFileObject[/full/path/to/Source.java]] [javadoc] [parsing completed 6ms]

5. No errors are being emitted for this class (there are warnings and errors for other source files, but not this one).

6. I have not run out of disk space.

Any ideas for how to get more information from javadoc or to see why this class might be ignored?

Answer 1

It turns out that this was a boneheaded error on top of a boneheaded error.

The real problem was that I was passing an invalid argument to javadoc which was a bit hidden due to my use of Apache Ant:

javadoc -source '${src.spec}' ...

My ant-based build script was adding that invalid -source value to the command-line. Javadoc was going through the motions, but not actually generating any files. Also not emitting any errors for that matter. :(

The second problem was that the clean target I had in my build script was not removing the old javadoc files, so running ant clean javadoc was changing nothing on the disk. Re-loading the "generated" javadoc was in fact just browsing API docs that had been generated long in the past. My new class wasn't a part of that run, so it wasn't showing up.

Fixing the -source argument to javadoc got things working again.

Answer 2

Sorry I do not have enough reputation to leave a comment. Have you tried using Netbeans "Analyze javadoc" feature? It goes through the whole project and shows you where something might be wrong and even suggests fixes too. It can be found at

Tools >> Analyze javadoc

when you have a project selected.

EDIT

Do you have any public methods inside of the class that are not commented for javadoc? If not then it may not recognize that the class needs to be added to the documentation since there is nothing there.