javadoc - how to document packages

Engines, Libraries and Tools Tools Discussion
#1

Hey,
I have not used javadoc and would like to start - I usually develope my own api (usually included in my users manual); however, I think the users of the software I am currently developing will benifit from the javadoc style most java developers are occustomed to.

Anyways, I have looked at sun’s site on java doc and found this

http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#sourcefiles

and

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Both talk about package level comments. You basicaly but a package.html file in the root of each package directory. For instance, you have a package called foo.bar with a class in foo/bar/Old.java
What I want to do is document each root directory.

foo/package.html
foo/bar/package.html

I want to describe the package foo in this html file but I do not want any .java files in the root of foo (its not approriate here)

I get an error from java doc when I do this
javadoc foo
javadoc: No source files for package foo

However, if I do javadoc foo.bar.Old then it produces semi-right stuff (it doesn’t include the comments I had in the package.html found in foo/bar/)

Anyone have any suggestions? Can you have a package.html w/out a coresponding .java file?

#2

[quote]Anyone have any suggestions? Can you have a package.html w/out a coresponding .java file?
[/quote]
I don’t think so. An empy package may as well not exists.

Why do you want an empty package? If you’re trying to create a “plugins” package or something where classes are loaded at runtime from that package you may find SPI useful.

#3

I want a package that doesn’t not have any .java files because all of the packages below it don’t make sense by themselves.

For instance, say you have a program that has a client and server. It would be nice to connect them by some global package name.

So you could have foo.client and foo.server.
So you could have package level comment about foo.

Does that make sense?

#4

This is what I want to do …

http://java.sun.com/j2se/1.4/docs/api/overview-summary.html

THere are no classes in this package; however, there are packages

#5

Ok, Found a solution to my own question.

You can do what I’m talking about but instead of using a package.html file in the root directory, put an overview.html file (it can be the same format as package.html).

Run javadoc -overview foo/overview.html -subpackages foo

Oh yea, make sure you do
unset CLASSPATH
b/c javadoc might try to run through your classes twice and complain about duplicate entries.