7.8 Method and function comments

In methods and named functions, parameter and return types must be documented,except in the case of same-signature @overrides, where all types are omitted.The this type should be documented when necessary. Return type may be omittedif the function has no non-empty return statements.

Method, parameter, and return descriptions (but not types) may be omitted ifthey are obvious from the rest of the method’s JSDoc or from its signature.

Method descriptions begin with a verb phrase that describes what the methoddoes. This phrase is not an imperative sentence, but instead is written in thethird person, as if there is an implied This method … before it.

If a method overrides a superclass method, it must include an @overrideannotation. Overridden methods inherit all JSDoc annotations from the superclass method (including visibility annotations) and they should be omitted inthe overridden method. However, if any type is refined in type annotations, all@param and @return annotations must be specified explicitly.

  1. /** A class that does something. */
  2. class SomeClass extends SomeBaseClass {
  3.   /**
  4.    * Operates on an instance of MyClass and returns something.
  5.    * @param {!MyClass} obj An object that for some reason needs detailed
  6.    *     explanation that spans multiple lines.
  7.    * @param {!OtherClass} obviousOtherClass
  8.    * @return {boolean} Whether something occurred.
  9.    */
  10.   someMethod(obj, obviousOtherClass) { ... }
  12.   /** @override */
  13.   overriddenMethod(param) { ... }
  14. }
  16. /**
  17.  * Demonstrates how top-level functions follow the same rules.  This one
  18.  * makes an array.
  19.  * @param {TYPE} arg
  20.  * @return {!Array<TYPE>}
  21.  * @template TYPE
  22.  */
  23. function makeArray(arg) { ... }

If you only need to document the param and return types of a function, you mayoptionally use inline JSDocs in the function's signature. These inline JSDocsspecify the return and param types without tags.

  1. function /** string */ foo(/** number */ arg) {...}

If you need descriptions or tags, use a single JSDoc comment above the method.For example, methods which return values need a @return tag.

  1. class MyClass {
  2.   /**
  3.    * @param {number} arg
  4.    * @return {string}
  5.    */
  6.   bar(arg) {...}
  7. }
  1. // Illegal inline JSDocs.
  3. class MyClass {
  4.   /** @return {string} */ foo() {...}
  5. }
  7. /** Function description. */ bar() {...}

In anonymous functions annotations are generally optional. If the automatic typeinference is insufficient or explicit annotation improves readability, thenannotate param and return types like this:

  1. promise.then(
  2.     /** @return {string} */
  3.     (/** !Array<string> */ items) => {
  4.       doSomethingWith(items);
  5.       return items[0];
  6.     });

For function type expressions, see ??.