Javadoc: package.html or package-info.java

java

javadoc

annotations

package-info-java

byAlex Kataev·Feb 26, 2025

Choose package-info.java over package.html for Java package documentation. package-info.java supports annotations, which gives you features like framework integration and type safety. Also, IDEs like package-info.java for its consistency and the ability to include versioning tags like @since.

Example:

/**
 * Your first class is...well, you guessed it! A package!
 * A glamorous package for applet tools and communication interfaces. 
 * Always staying on trend 😉.
 * 
 * @since Version 1.2 (Yeah! The Applet party started here!)
 */
@FrameworkAnnotation // Don't forget your 'formal wear' - annotation
package com.example.applet;

import com.example.framework.FrameworkAnnotation;

Key Tip: If you want to be in the "modern Java code documentation club," use package-info.java. You'll thank me later!

Why package-info.java is the go-to choice

package-info.java earns the top spot in Java's package documentation playbook, thanks to its unique properties. It provides a structured framework for maintaining comprehensive, package-level comments. Consider it the "Wikipedia page" of your package!

Annotate all things: With package-info.java, you can use annotations that apply to every class in the package. A timesaver, trust me!

Readability at its finest: package-info.java gives your comments and descriptions a special home, away from the code clutter, promoting code maintenance and stellar team communication.

Say goodbye to merge conflicts: Your documentation gets a sweet separation from your source code, simplifying version control and minimizing merge conflicts.

BFFs with tools: package-info.java works and plays well with the Java documentation toolchain including Javadoc.

Future-proof: As Java evolves, package-info.java is bound to stay relevant and adaptable.

Harnessing the power of annotations and tags

Annotations: The secret sauce

package-info.java allows us to flex our muscles with package-level annotations, a key tool for framework integration and type safety enforcement at the codebase's higher levels.

Versioning tags: The historian

Using tags like @since within your package-info.java helps keep a timeline of your package's evolution – remarkably beneficial for managing codebases that stick around like a classic rock band.

About Deprecated: The caution tape

Pairing package-info.java with the @Deprecated annotation lets you declare the obsolescence of entire packages. This is essentially a "Do not use. Construction ahead" sign for developers!

The good, the bad, and the code

From package.html to package-info.java: The great migration

If you're maintaining legacy code, going from package.html to package-info.java may feel like conquering Everest. It's doable, though, with a slow and steady approach. The advantages of annotations, tool support, and structured docs easily justify the climb.

Avoid the annotation avalanche

As you sprinkle annotations, prevent duplicates and conflicts with class-level annotations. Or else, you might unleash a torrent of unintended behavior - a developer's nightmare!