40

I use javadoc to document my classes and methods. I would like to add some overview information to my packages, too. I like how Eclipse creates a stub of a matching Doc Comment for each class or method once I type /**<Enter>. Does Eclipse have an easy way to generate a package.html file, too?

Hanno Fietz
  • 30,799
  • 47
  • 148
  • 234
  • 12
    Just a note: as of Java 1.5, the preferred location for package comments is package-info.java, not package.html. This way, it is also possible to define package-level annotations. See http://java.sun.com/javase/6/docs/technotes/guides/javadoc/whatsnew-1.5.0.html – Michael Myers May 21 '09 at 15:19

4 Answers4

51

Update 4 years later (Oct. 2013)

javabeangrinder's answer (upvoted) mentions the following trick:

To create a package-info.java file in an existing package:

  • Right click on the package where you want a package-info.java.
  • Select new->package.
  • Check the Create package.info.java check box.
  • Click on Finish

Original answer (May 2009)

There is no template or wizard to easily create a package.html file.

As mmyers said in his comment, since Java1.5, the correct file to create would be package-info.java.
That file can be used not only for javadocs, but also for package-level annotations (as illustrated here).

There is an opened Bug (#86168) for demanding a wizard for the creation of package-info.java (since the class wizard does not allow the package-info name).

The reflections on that topic are on since... 2005! The problem is that any solution should be implemented in a way that it also helps with 1.4 code.

The current workaround is to create a package-info.java as a text file.
From that point forward, package-info.java behaves as a normal Java class, and Eclipse places a package-info.class file in the output folder.
The Javadocs are correctly built using package-info.java, and not the package.html file.

alt text
(source: developpez.com)

Note (in response to Strawberry's comment):

both wish a preview of the package overview in package-info.java in the Javadoc view.

So far, no patch has been proposed/implemented.
There is simply not enough demands for that feature to be added.

Glorfindel
  • 21,988
  • 13
  • 81
  • 109
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • 1
    Is there anyway to get the package javadocs to show in the Javadoc fast view window - as they do for classes, interfaces and methods? – Martin Dec 19 '09 at 00:49
  • 1
    @Strawberry: nope, no Javadoc view for package-info.java. See my extended answer on that. – VonC Dec 19 '09 at 07:13
  • Note to self, after [this question](http://stackoverflow.com/a/9600531/6309), I got to cross over 200K *again*! (due to some [rep recalc](http://meta.stackexchange.com/questions/125121/has-reputation-for-deleted-posts-been-removed-again)) – VonC Mar 10 '12 at 11:26
  • @Mr_and_Mrs_D Good solution indeed. I have included it and notified his author. – VonC Oct 22 '13 at 19:01
15

In eclipse

Since package-info.java isn't a valid identifier for a class it cannot be created as a class in Eclipse.

I found that when you create a new package there is a check box to check if you want a package-info.java.

To create a package-info.java file in an existing package:

  1. Right click on the package where you want a package-info.java.
  2. Select new->package.
  3. Check the Create package.info.java check box.
  4. Click on Finish
javabeangrinder
  • 6,939
  • 6
  • 35
  • 38
13

The JAutodoc plugin does a great job of this, as well as all your other documentation needs. Install and configure the plugin and right click the package and click JAutodoc > Add Package Javadoc

There are configurations and templates available for the .java or .html package documentation.

This plugin also does a great job of standardizing all your Javadoc needs, with a great deal of customization.

http://jautodoc.sourceforge.net/

Community
  • 1
  • 1
NathanChristie
  • 2,374
  • 21
  • 20
3

There's a plugin that seems to create package.html files. I haven't used it but someone landing here might find it useful.

http://sourceforge.net/projects/package-javadoc/

gMale
  • 17,147
  • 17
  • 91
  • 116