JavaDoc and summary fragments

[Boris Sazonov]

Hi folks,

Sharing with the larger team a discussion that we had in a code review.

When writing JavaDocs, we should prefer /** Returns the customer ID. */ instead of /** @return the customer ID */.

Justification:

Per JavaDoc documentation, all JavaDocs should have a summary sentence:

The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item.

Google Java style guide expands on this guidance and provides one important clarification:

A common mistake is to write simple Javadoc in the form /** @return the customer ID */. This is incorrect, and should be changed to /** Returns the customer ID. */.

Cheers,

Boris

[Nate Fischer]

Are you saying that "@return" is banned for all Javadoc, or does this only apply to single-sentence Javadoc? I'd like to keep "@return" for multi-sentence Javadoc since this is part of the Javadoc spec and it's used widely in AOSP.

Nate Fischer | Software Engineer | ntf...@google.com

--
You received this message because you are subscribed to the Google Groups "java" group.
To unsubscribe from this group and stop receiving emails from it, send an email to java+uns...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/java/CAPtdB4knsYYZqspVJRhkaVqnDEbyCMJLrpug_xXHprZAyw7Q4Q%40mail.gmail.com.

[Ted Choc]

On Wed, Jul 12, 2023 at 10:00 AM 'Nate Fischer' via java <ja...@chromium.org> wrote:

Are you saying that "@return" is banned for all Javadoc, or does this only apply to single-sentence Javadoc? I'd like to keep "@return" for multi-sentence Javadoc since this is part of the Javadoc spec and it's used widely in AOSP.

By multi-sentence, do you mean where the @return statement has multiple sentences, or when there are multiple components to a Javadoc?

This definitely wasn't a "ban all use of @return", but for cases where your javadoc only has the @return line and nothing else, you should drop the use of the @return entirely.

Below would still completely be valid and allowed

/**

 * Generates important foo and bars.

 * @param id The foo ID.

 * @return The success code of the operation.

 */

But we would be discouraging:

/** @return The success code of the operation. */

And instead it should be:

/** Return the success code of the operation. */

- Ted

 

Nate Fischer | Software Engineer | ntf...@google.com

On Wed, Jul 12, 2023 at 6:53 AM Boris Sazonov <bsaz...@chromium.org> wrote:

Hi folks,

Sharing with the larger team a discussion that we had in a code review.

When writing JavaDocs, we should prefer /** Returns the customer ID. */ instead of /** @return the customer ID */.

Justification:

Per JavaDoc documentation, all JavaDocs should have a summary sentence:

The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item.

Google Java style guide expands on this guidance and provides one important clarification:

A common mistake is to write simple Javadoc in the form /** @return the customer ID */. This is incorrect, and should be changed to /** Returns the customer ID. */.

Cheers,

Boris

--
You received this message because you are subscribed to the Google Groups "java" group.
To unsubscribe from this group and stop receiving emails from it, send an email to java+uns...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/java/CAPtdB4knsYYZqspVJRhkaVqnDEbyCMJLrpug_xXHprZAyw7Q4Q%40mail.gmail.com.

--
You received this message because you are subscribed to the Google Groups "java" group.
To unsubscribe from this group and stop receiving emails from it, send an email to java+uns...@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/java/CACiwn8Z2aLcvFXspu4KtFVGfB7S3T_%3D8XDBjtkRBW55kd26GXg%40mail.gmail.com

[Nate Fischer]

Ok, that policy SGTM. If this is going into the style guide, please clarify this guidance applies only to the first sentence of Javadoc and that longer javadoc may still use "@return".

Nate Fischer | Software Engineer | ntf...@google.com