API Documentation

API documentation explains how consumers should use public classes, methods, configuration, and behavioral contracts. Good documentation makes an API predictable without requiring readers to inspect its implementation.

API documentation describes the public surface of a Java component and the rules consumers must follow. For a class or method, that commonly includes its purpose, parameters, return value, exceptions, side effects, and important usage constraints.

In Java, `Javadoc` is the standard mechanism for documenting public APIs. Documentation comments can use tags such as `@param`, `@return`, `@throws`, and `@see`, and tools can turn them into browsable reference documentation.

Documentation should describe observable behavior rather than implementation details. If a method promises that an argument must be non-null, returns a particular value under a condition, or throws a specific exception for invalid input, that contract belongs in the documentation.

Good API documentation also explains configuration and examples when they help consumers use the API correctly. It should stay synchronized with the implementation because stale documentation can cause users to write code based on behavior the API no longer provides.

Key points

• Document the public API and its observable behavior.
• Use Javadoc for Java classes, methods, parameters, returns, and exceptions.
• Describe preconditions, postconditions, side effects, and important constraints.
• Keep documentation consistent with the actual implementation.
• Prefer concise examples when behavior is not obvious from the API signature.

Interview questions

What should good API documentation contain?

It should explain what the API does and how a consumer is expected to use it. For methods, that includes meaningful descriptions of parameters, return values, exceptions, and important constraints. It should focus on observable behavior rather than internal implementation details.

What is Javadoc, and why is it useful?

Javadoc is Java's documentation-comment format and tooling convention for describing program elements such as classes and methods. Tags such as `@param`, `@return`, and `@throws` provide structured information about an API. Documentation tools can use these comments to generate reference material for developers.

Why should API documentation focus on behavior rather than implementation?

Consumers depend on what an API guarantees, not on how its implementation currently works. Implementation details can change without breaking the public contract, so exposing them creates unnecessary coupling. Documentation should therefore describe inputs, outputs, side effects, constraints, and other observable behavior.

How would you keep API documentation from becoming stale?

I would treat documentation as part of the API change process rather than as an afterthought. Changes to public behavior should update the relevant Javadoc, examples, and generated documentation in the same change. Code review and automated documentation generation can help catch omissions, although tests are still needed to verify behavior.

What is the difference between documenting a method signature and documenting its contract?

A method signature tells consumers the types and names involved, but it does not necessarily explain the semantics. The contract defines conditions such as valid inputs, returned meaning, side effects, ordering guarantees, and failure behavior. Good API documentation fills in those semantic details without exposing unnecessary implementation mechanics.