Javadoc style guide: when to use `{@code}`

[javier-godoy]

In each comment, the first occurrence of an identifier that refers to a class, field, or method must be enclosed in a {@link} tag. Otherwise, the identifier must be wrapped in {@code} (or <code> see #39).

The following identifiers must never be linked and should always be wrapped in {@code}:

• The name of the type being documented, or the type where the documented method/field is located.
• The names of the field type, method return type, and argument types.
• Exceptions listed in the throws` clause of the documented method.
• The names of the direct supertype and any implemented interfaces of the documented type (in a type-level comment).

  /**
   * Creates a new instance of {@code FooBar}.
   */
  public FooBar() { ... }

[elPeiretti]

I agree, it makes the docs much easier to read compared to having it all in plain text.

[elPeiretti]

Regarding the second rule: The names of the field type, method return type, and argument types must never be linked.

I would also add: If mentioned, they must be wrapped in {@code}

  /*
   *  ....
   * @param picture the {@code Picture} to display in the frame.
   */
  public void setPicture(Picture picture) {}

[javier-godoy]

Regarding the second rule: The names of the field type, method return type, and argument types must never be linked.

I would also add: If mentioned, they must be wrapped in {@code}

+1. I added the following clarification:

- The following identifiers must never be linked: 
+ The following identifiers must never be linked and should always be wrapped in `{@code}:`