CODEWITHSUNDEEP
javajavadoc
Adam Burley
Adam Burley

Reputation: 6069

Is the author tag required in JavaDoc or not?

Regardless of common convention / best-practice (as I know many people deride @author as bad-practice), but instead relying on official sources, is the @author tag required in JavaDoc or not?

Investigating this question, I looked into Oracle's own documentation at http://www.oracle.com/technetwork/articles/java/index-137868.html (this is also the first result in Google when searching for 'javadoc tags').

In a section called "order of tags", they say:

Include tags in the following order:

  • @author (classes and interfaces only, required)
  • @version (classes and interfaces only, required. See footnote 1)
  • @param (methods and constructors only)
  • @return (methods only)
  • @exception (@throws is a synonym added in Javadoc 1.2)
  • @see
  • @since
  • @serial (or @serialField or @serialData)
  • @deprecated (see How and When To Deprecate APIs)

Here it seems that @author is marked as "required", even when something like @return is not. This seemed quite strange to me. Indeed, later on in the exact same document I found the following statement:

You can provide one @author tag, multiple @author tags, or no @author tags.

This seems to me to be a complete contradiction. If you can provide no @author tags, surely it's not "required"!

Have I misread something or is this just poorly-written documentation?

Upvotes: 0

Views: 2214

Answers (2)

user207421
user207421

Reputation: 310883

The document you are citing is a style guide, not the Javadoc specification:

This document describes the style guide, tag and image conventions we use in documentation comments for Java programs written at Java Software, Oracle.

It is not an 'official source' for anything, unless you work at Oracle.

Upvotes: 3

d.j.brown
d.j.brown

Reputation: 1842

I would say poorly written documentation.

The next paragraph says:

The @author tag is not critical, because it is not included when generating the API specification, and so it is seen only by those viewing the source code. (Version history can also be used for determining contributors for internal purposes.)

Additionally, no where is these tech notes can I see a statement stating it is required http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#javasourcefiles

Upvotes: 1

Related Questions