Javadoc question re Eclipse

[Rhino]

I've just discovered that it is possible to create package-level Javadoc
comments in Java 1.5.0 by putting them in a file called package-info.java. I
like the idea of documenting my packages but I'm finding the documentation
unclear on where exactly this package-info.java file is placed, particularly
when I'm using Eclipse. The documentation seems to be saying that I should
put this file in my source tree under the package being documented.

I tried creating a Class named package-info in Package Explorer within the
package which I'm trying to document but Eclipse wouldn't let me do this: it
didn't want to create a Class named package-info. The same problem occurred
when I tried to create an annotation named package-info within my package.
Then I created a File named package-info.java in my package and put a single
Javadoc comment in it:

/**
@author Fred Flintstone
*/

but when I generated my Javadocs, this Author information doesn't show up.

Therefore, I have the following questions:

1. What type should the package-info.java file be, e.g. File, Class,
Annotation, or something else?
2. Where do I put this file so that this documentation appears in my
Javadocs at the appropriate page?
3. Do I need to modify my current Javadocs generation step - I'm using the
Javadoc task in Ant - to pick up these package-info files? If yes, what
changes do I need to make?

 

[Oliver Wong]

I've just discovered that it is possible to create package-level Javadoc
comments in Java 1.5.0 by putting them in a file called package-info.java.
I
like the idea of documenting my packages but I'm finding the documentation
unclear on where exactly this package-info.java file is placed,
particularly
when I'm using Eclipse. The documentation seems to be saying that I should
put this file in my source tree under the package being documented.

I tried creating a Class named package-info in Package Explorer within the
package which I'm trying to document but Eclipse wouldn't let me do this:
it
didn't want to create a Class named package-info. The same problem
occurred
when I tried to create an annotation named package-info within my package.
Then I created a File named package-info.java in my package and put a
single
Javadoc comment in it:

/**
@author Fred Flintstone
*/

but when I generated my Javadocs, this Author information doesn't show up.

Therefore, I have the following questions:

1. What type should the package-info.java file be, e.g. File, Class,
Annotation, or something else?
2. Where do I put this file so that this documentation appears in my
Javadocs at the appropriate page?
3. Do I need to modify my current Javadocs generation step - I'm using the
Javadoc task in Ant - to pick up these package-info files? If yes, what
changes do I need to make?

I don't know about Eclipse, but according to
http://java.sun.com/j2se/javadoc/writingdoccomments/

<quote>
Each package can have its own package-level doc comment source file that The
Javadoc tool will merge into the documentation that it produces. This file
is named package.html (and is same name for all packages). This file is kept
in the source directory along with all the *.java files. (Do not put the
packages.html file in the new doc-files source directory, because those
files are only copied to the destination and are not processed.)
</quote>

- Oliver

 

[Roedy Green]

1. What type should the package-info.java file be, e.g. File, Class,
Annotation, or something else?

I have not experimented, but I would hazard guess this is a simple
kludge. You write an empty java class called package-info.java. You
put in the package directory Note they violated the naming
conventions so this should not conflict with any real class.

Perhaps you leave out the public class statement.

 

[Rhino]

I don't know about Eclipse, but according to
http://java.sun.com/j2se/javadoc/writingdoccomments/

<quote>
Each package can have its own package-level doc comment source file that
The Javadoc tool will merge into the documentation that it produces. This
file is named package.html (and is same name for all packages). This file
is kept in the source directory along with all the *.java files. (Do not
put the packages.html file in the new doc-files source directory, because
those files are only copied to the destination and are not processed.)
</quote>

Yeah, I read that too. But I'm having trouble actually CREATING the file
containing the document in Eclipse. (Actually, package-info.java seems to be
the preferred file to use in newer versions of the Javadoc documentation.) I
finally managed to create a package-info.java by making it a File instead of
a Class or Annotation, but Javadoc doesn't seem to be picking it up.

The Eclipse documentation is no more helpful in defining exactly how to
create this document. I've asked at the Eclipse forums but haven't received
any answers yet in a very active forum.

Rhino

 

[Rhino]

I have not experimented, but I would hazard guess this is a simple
kludge. You write an empty java class called package-info.java. You
put in the package directory Note they violated the naming
conventions so this should not conflict with any real class.

Perhaps you leave out the public class statement.

As I said, I tried creating a Class and an Annotation named
package-info.java but this was not allowed. I was allowed to create a File
named package-info.java but the file doesn't seem to be getting picked up in
the Javadoc which makes me wonder what type package-info is supposed to be!

I've had no answers on the Eclipse forum and found nothing helpful in the
Eclipse documentation.

*Somebody* must have done this but I'm not having much luck finding out how
to do create this document and get it integrated into my Javadocs.

Rhino

 

[Roedy Green]

The Eclipse documentation is no more helpful in defining exactly how to
create this document. I've asked at the Eclipse forums but haven't received
any answers yet in a very active forum.

One of the easiest ways to create files it to do a save as with a new
name. Then patch.

 

[Roedy Green]

I've just discovered that it is possible to create package-level Javadoc
comments in Java 1.5.0 by putting them in a file called package-info.java.

I got it to work. I have documented the various bits of magic to make
it work at http://mindprod.com/jgloss/javadoc.html#PACKAGE

It is all completely logical once you see it.

 

[Raymond DeCampo]

Yeah, I read that too. But I'm having trouble actually CREATING the file
containing the document in Eclipse. (Actually, package-info.java seems to be
the preferred file to use in newer versions of the Javadoc documentation.) I
finally managed to create a package-info.java by making it a File instead of
a Class or Annotation, but Javadoc doesn't seem to be picking it up.

The Eclipse documentation is no more helpful in defining exactly how to
create this document. I've asked at the Eclipse forums but haven't received
any answers yet in a very active forum.

In terms of creating the file in Eclipse, note that you are not creating
a class called "package-list". All you are doing is creating a file.
Note that it is perfectly legal to create a file named xyz.java (or
---.java or 777.java) and have it be empty or contain non-public classes
or contain simply comments. The compiler will not have an issue with this.

My first reaction to this news that package-info.java is the preferred
place for package-level documentation was WTF. Why would I want a
spurious java file that contains only documentation? What was wrong
with package.html? Then I remembered that annotations are available at
runtime, so the file may not be spurious after all.

HTH,
Ray

 

[Rhino]

I got it to work. I have documented the various bits of magic to make
it work at http://mindprod.com/jgloss/javadoc.html#PACKAGE

It is all completely logical once you see it.

I see I was right in guessing that the package-info.java had to be a File,
not a Class or Annotation. It was also useful to see that I needed a package
statement in the package-info file; for some reason, I thought that was
implied by the positioning of the file and I didn't need to add it.

When I generated the javadocs with Ant again, I still didn't see the
information from the package-info file. However, when I generated my
Javadocs with the Javadoc option in Eclipse, my package-info remarks showed
up just fine. Clearly, I've got something wrong in the parameters of the Ant
Javadoc task; I'll chase that down now that I've proven the comments will
show up if generated via Eclipse's Javadoc option.

Thanks for your efforts in documenting how package-info works. I'm going to
post to the Eclipse forums and suggest that they improve their
documentation.

Rhino