-overview flag weirdness
I'm using the following javadoc command running in a shell script, and this works fine (yeah it's JDK 1.2.2 - don't bite my head off).
javadoc -link http://server/jdoc/jdk1.2.2/docs/api/ \
-J-Xmx32m \
-d /IBMHTTPD/jdoc \
-use \
-splitIndex \
-windowtitle"Framework Title" \
-header"<img src=doc-files/small_Logo_Color.gif width=150 height=41 border=0 >" \
-package @packages.txt
I've got package.html files throughout the source tree that let me document each package, and I want to add info to the package overview page. The problem is that when I add the -overview flag like so:
javadoc -overview /path/to/overview.html \
-link http://server/jdoc/jdk1.2.2/docs/api/ \
-J-Xmx32m \
-d /IBMHTTPD/jdoc \
-use \
-splitIndex \
-windowtitle"Framework Title" \
-header"<img src=doc-files/small_Logo_Color.gif width=150 height=41 border=0 >" \
-package @packages.txt
The whole thing tanks with an error: javadoc: No packages or classes specified
The syntax looks right, and I've tried putting the -overview flag all over the place. The best result I've been able to get is a command that both doesn't fail, but also doesn't put the text from the specified overview file onto the overview page. I know I'm asking for it here - but where do I stick it?
Cheers, Michael
Does your error message say this:
javadoc: No package, class, or source file found named .
If so, I would bet two things:
1) You haven't tried putting the -overview statement at the very end, on the line after @package.txt
2) There is a space after the continuation character (slash) at the end of the -overview line. Remove this space and it will work.
The shell passes "\ " (backslash-space) to javadoc in such a way that it interprets it as a package whose name is " " (a space).
We improved the error message in 1.4.0 to enclose the name in quotes so there is a better indication of what's happening, though it's still quite cryptic.
Looking at the way you have formatted your script, I think you might misunderstand what -package option does. It does not take any arguments. It means include all package-private (as well as public and protect) classes and members, which is nornally not what developers want. (They either want the default access, which is -protected, or show everything, which is -private.) You can supply @packages.txt alone on its own as the last line.
Here's the documentation for -package:
http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#package
Happy coding,
-Doug Kramer
Javadoc team
BTW, this is documented in the Javadoc FAQ at: http://java.sun.com/j2se/javadoc/faq/index.html#shellscript-Doug
Thanks Doug -
I found the FAQ entry about the backslash / whitespace issue in shell scripts after I posted this.
The other issue with -package is a typo in the script: Initially, the javadoc command was a one-liner, which got progressively longer and difficult to read. When we broke it across multiple lines with the continuation char, we didn't break the -package from the @package. We want to document the package, public and protected members.
I've fixed this, but the -overview flag still doesn't include the contents of the specified overview html file in the generated javadoc.
Here's the current command:
javadoc \
-link http://server/jdk1.2.2/docs/api/ \
-J-Xmx32m \
-d /opt/IBMHTTPD/htdocs/jdoc \
-use \
-splitIndex \
-windowtitle "Framework Title" \
-header "<img src=doc-files/small_Logo_Color.gif width=150 height=41 border=0 >" \
-package \
@packages.txt \
-overview /path/to/overview.html
Any other ideas?
Cheers, Michael
Perhaps your overview.html file does not contain a <BODY> tag?
Only text following the <BODY> tag is included. This is how we prevent it from including the <HTML> and <HEAD> info.
If that's the case, we should check to see if 1.4.0 emits a warning in such a case.
BTW, I normally wouldn't put the -overview flag at the end -- I was just suggesting you hadn't tried putting it there, or the problem with no packages wouldn't have occurred (because it wouldn't have a continuation character). I would move it back to where it makes more logical sense.
-Doug Kramer
Thanks for you help Doug, there was a <BODY> tag, but the </BODY> tag was missing. I added this to the file and this fixed the problem. I suppose that it got edited out somwhere along the line and nobody noticed.
The Javadoc tool docs mention this about the overview file: Copies all content between <body> and </body> tags for processing.
Looks like I stepped on a feature, not a bug.
Thanks again.
Cheers, Michael
I'll copy that sentence about processing between <body> and </body> to the javadoc.html reference page from the underlying overview page. It deserves higher prominence. Even I overlooked it in my first email, after referring to the docs.
Thanks for bringing this to our attention.
-Doug
