Javadocs

Main ideas / concepts

• Javadoc (Java docs) is a standard for commenting Java programs.
• The term “Java doc” can refer to both:
  • the tool used to generate documentation, and
  • the commenting style/syntax used in Java code.
• The purpose of Javadoc comments is to add notes to code so other people can understand it.
• Javadoc is widely used because it provides a common reference point for developers.

Javadoc comment rules (methodology / formatting)

• Start/end syntax:
  • Javadoc comments start with /*** (i.e., /** followed by an extra * in the phrasing).
  • They end with */.
• The structure is similar to a multi-line comment, but with Javadoc-specific conventions.

Javadoc special tags (key instruction list)

Javadoc supports special tags (many exist). The focus here is on:

• @param

  • Used to document a method parameter.
  • Conceptual syntax: @param <name> <description>

• @return

  • Used to document the value returned by the method.
  • Conceptual syntax: @return <description>

Example structure conveyed (as a template)

The example centers on a method (referred to as sum) and follows a standard pattern:

• Start with a plain-text Javadoc description of the method.
• Add one @param tag for each parameter, including:
  • the parameter name
  • what the parameter represents
• Add a single @return tag describing what the method returns.

General format (explicitly outlined)

1. A description of the method
2. One @param tag per parameter:
   • include the parameter name and a description for each
3. One @return tag:
   • include a description of the returned value

Lesson / takeaway

• Use Javadoc comments (including @param and @return) to make Java code easier for others to understand.

Speakers / sources featured

• No specific speakers are identified in the provided subtitles.