Effective Java

---

CHAPTER 8
METHODS
254
Item 56: Write doc comments for all exposed API elements
If an API is to be usable, it must be documented. Traditionally, API documentation
was generated manually, and keeping it in sync with code was a chore. The Java
programming environment eases this task with the 
Javadoc
utility. Javadoc
generates API documentation automatically from source code with specially
formatted 
documentation comments
, more commonly known as 
doc comments
.
While the doc comment conventions are not officially part of the language,
they constitute a de facto API that every Java programmer should know. These
conventions are described in the 
How to Write Doc Comments
web page [Javadoc-
guide]. While this page has not been updated since Java 4 was released, it is still
an invaluable resource. One important doc tag was added in Java 9, 
{@index}
; one
in Java 8, 
{@implSpec}
; and two in Java 5, 
{@literal}
and 
{@code}
. These tags
are missing from the aforementioned web page, but are discussed in this item.