Javadoc: Inheritance, package-info & the javadoc Tool

{@inheritDoc}: Avoiding Duplicated Docs

public interface Repository<T> {
    /**
     * Persists the given entity.
     * @param entity the entity to save, must not be null
     * @return the saved entity, with any generated fields populated
     */
    T save(T entity);
}

public class UserRepository implements Repository<User> {
    /**
     * {@inheritDoc}
     *
     * <p>Additionally publishes a UserCreatedEvent on first save.
     */
    @Override
    public User save(User entity) {
        // ...
    }
}
// The @param/@return/description are pulled in from the interface
// automatically -- avoiding copy-pasted docs drifting out of sync
// between the contract and each implementation.

Package-Level Documentation

// src/main/java/com/example/orders/package-info.java
/**
 * Order processing and fulfillment logic.
 *
 * <p>This package handles the full order lifecycle: creation,
 * payment authorization, fulfillment, and cancellation.
 */
package com.example.orders;

// A package itself has no single class to attach a doc comment to --
// package-info.java gives the javadoc tool a place to generate the
// package summary page.

Generating Documentation

# Generate consumer-facing docs -- public API surface only
javadoc -public -d docs/api -sourcepath src/main/java com.example.orders

# Internal/maintainer docs -- includes private members too
javadoc -private -d docs/internal -sourcepath src/main/java com.example.orders

# Maven/Gradle equivalents (typically run as part of a docs/release step)
# mvn javadoc:javadoc
# ./gradlew javadoc

# Build-time validation: configured to warn/fail on a missing @param,
# a broken {@link} reference to a renamed method, etc. -- catches
# documentation drift automatically rather than relying on manual review.

Doclets & Related Conventions

• A doclet is the pluggable output-generation component -- the default doclet produces HTML, but custom doclets can produce other formats or apply custom processing.

• -public/-private/-protected/-package flags control which access-level members appear in the generated docs, letting the same source comments serve different audiences.

• Javadoc heavily influenced later doc-comment conventions -- JSDoc (JavaScript) directly borrows much of its tag vocabulary (@param, @returns, @throws).