Java Reference
In-Depth Information
18.5. Package Annotations
A package can have annotations applied to it. The problem is that there
is no actual definition of a package to which you can apply such annota-
tionsunlike a class or a methodbecause a package is an organizational
structure, not a source code entity. So you annotate packages by apply-
ing the annotation to the package statement within a source file for that
package. However, only one package declaration per package can have
annotations applied to it.
So how do you actually annotate a package? There is no required way to
deal with this "single annotated package statement" rule. The suggested
approach is to create a file called
package-info.java
within the package
directory, and to put in that file nothing but a package statement with
any annotations for the package (plus any useful comments, of course).
For example, a
package-info.java
file for the
attr
package might look like
this:
@PackageSpec(name = "Attr Project", version = "1.0")
@DevelopmentSite("attr.project.org")
@DevelopmentModel("open-source")
package attr;
where
PackageSpec
,
DevelopmentSite
, and
DevelopmentModel
are made up an-
notation typeswith a runtime retention policy, of course. The
package-
info.java
file should be compiled along with the rest of the package
source files.
The
package-info.java
file is recommended as the single place to put all
package-related information. To that end, you can place a documentation
comment at the start of the file, and that will be the package document-
ation for that package. Package documentation is covered in more detail
in "
Package and Overview Documentation
" on page
496
.
