From 0153155e24045c5b4ffae7ccf412a45672fab8b6 Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Mon, 1 Jul 2024 22:03:21 -0400 Subject: [PATCH] jsguide: update classes to match newer styles The rendering should be unchanged as the names should align with the underlying rules. --- jsguide.html | 294 +++++++++++++++++++++++++-------------------------- 1 file changed, 147 insertions(+), 147 deletions(-) diff --git a/jsguide.html b/jsguide.html index 9aca653..d07f67e 100644 --- a/jsguide.html +++ b/jsguide.html @@ -89,7 +89,7 @@ depending only on which makes the code easier to read and understandTip: In the Unicode escape case, and occasionally even when actual Unicode characters are used, an explanatory comment can be very helpful.

-
/* Best: perfectly clear even without a comment. */
+
/* Best: perfectly clear even without a comment. */
 const units = 'μs';
 
 /* Allowed: but unnecessary as μ is a printable character. */
@@ -99,7 +99,7 @@ const units = '\u03bcs'; // 'μs'
 return '\ufeff' + content;  // Prepend a byte order mark.
 

 
-
/* Poor: the reader has no idea what character this is. */
+
/* Poor: the reader has no idea what character this is. */
 const units = '\u03bcs';
 

 
@@ -146,7 +146,7 @@ that it defines concatenated to the end.

 
 
Example

 
-
goog.module('search.urlHistory.UrlHistoryService');
+
goog.module('search.urlHistory.UrlHistoryService');
 

 
 
3.3.1 Hierarchy

@@ -156,7 +156,7 @@ namespace.

 
 
Disallowed:

 
-
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
+
goog.module('foo.bar');   // 'foo.bar.qux' would be fine, though
 goog.module('foo.bar.baz');
 

 
@@ -173,7 +173,7 @@ child namespaces, since they exist in the same directory.

 
 
Example:

 
-
goog.module('my.test.helpers');
+
goog.module('my.test.helpers');
 goog.module.declareLegacyNamespace();
 goog.setTestOnly();
 

@@ -198,7 +198,7 @@ symbols.

 
 
Examples:

 
-
const /** !Array<number> */ exportedArray = [1, 2, 3];
+
const /** !Array<number> */ exportedArray = [1, 2, 3];
 
 const /** !Array<number> */ moduleLocalArray = [4, 5, 6];
 
@@ -215,7 +215,7 @@ function exportedFunction() {
 exports = {exportedArray, exportedFunction};
 

 
-
/** @const {number} */
+
/** @const {number} */
 exports.CONSTANT_ONE = 1;
 
 /** @const {string} */
@@ -225,7 +225,7 @@ exports.CONSTANT_TWO = 'Another constant';
 
Do not annotate the exports object as @const as it is already treated as a
 constant by the compiler.

 
-
/** @const */
+
/** @const */
 exports = {exportedFunction};
 

 
@@ -247,7 +247,7 @@ exports = {exportedFunction};
 
ES module files must use the import statement to import other ES module
 files. Do not goog.require another ES module.

 
-
import './sideeffects.js';
+
import './sideeffects.js';
 
 import * as goog from '../closure/goog/goog.js';
 import * as parent from '../parent.js';
@@ -262,10 +262,10 @@ import {name} from './sibling.js';
 
The .js file extension is not optional in import paths and must always be
 included.

 
-
import '../directory/file';
+
import '../directory/file';
 

 
-
import '../directory/file.js';
+
import '../directory/file.js';
 

 
 
3.4.1.2 Importing the same file multiple times

@@ -273,7 +273,7 @@ included.

 
Do not import the same file multiple times. This can make it hard to determine
 the aggregate imports of a file.

 
-
// Imports have the same path, but since it doesn't align it can be hard to see.
+
// Imports have the same path, but since it doesn't align it can be hard to see.
 import {short} from './long/path/to/a/file.js';
 import {aLongNameThatBreaksAlignment} from './long/path/to/a/file.js';
 

@@ -287,12 +287,12 @@ import {aLongNameThatBreaksAlignment} from './long/path/to/a/file.js';
 
Module import names (import * as name) are lowerCamelCase names that are
 derived from the imported file name.

 
-
import * as fileOne from '../file-one.js';
+
import * as fileOne from '../file-one.js';
 import * as fileTwo from '../file_two.js';
 import * as fileThree from '../filethree.js';
 

 
-
import * as libString from './lib/string.js';
+
import * as libString from './lib/string.js';
 import * as math from './math/math.js';
 import * as vectorMath from './vector/math.js';
 

@@ -302,7 +302,7 @@ import * as vectorMath from './vector/math.js';
 
Default import names are derived from the imported file name and follow the
 rules in ??.

 
-
import MyClass from '../my-class.js';
+
import MyClass from '../my-class.js';
 import myFunction from '../my_function.js';
 import SOME_CONSTANT from '../someconstant.js';
 

@@ -318,7 +318,7 @@ the same name. Avoid aliasing imports (import {SomeThing as SomeOtherThing
 Prefer fixing name collisions by using a module import (import *) or renaming
 the exports themselves.

 
-
import * as bigAnimals from './biganimals.js';
+
import * as bigAnimals from './biganimals.js';
 import * as domesticatedAnimals from './domesticatedanimals.js';
 
 new bigAnimals.Cat();
@@ -328,7 +328,7 @@ new domesticatedAnimals.Cat();
 
If renaming a named import is needed then use components of the imported
 module's file name or path in the resulting alias.

 
-
import {Cat as BigCat} from './biganimals.js';
+
import {Cat as BigCat} from './biganimals.js';
 import {Cat as DomesticatedCat} from './domesticatedanimals.js';
 
 new BigCat();
@@ -352,15 +352,15 @@ declaration, or use the export {name}; syntax.

 
Do not use default exports. Importing modules must give a name to these values,
 which can lead to inconsistencies in naming across modules.

 
-
// Do not use default exports:
+
// Do not use default exports:
 export default class Foo { ... } // BAD!
 

 
-
// Use named exports:
+
// Use named exports:
 export class Foo { ... }
 

 
-
// Alternate style named exports:
+
// Alternate style named exports:
 class Foo { ... }
 
 export {Foo};
@@ -371,7 +371,7 @@ export {Foo};
 
Do not export container classes or objects with static methods or properties for
 the sake of namespacing.

 
-
// container.js
+
// container.js
 // Bad: Container is an exported class that has only static methods and fields.
 export class Container {
   /** @return {number} */
@@ -386,7 +386,7 @@ Container.FOO = 1;
 
 
Instead, export individual constants and functions:

 
-
/** @return {number} */
+
/** @return {number} */
 export function bar() {
   return 1;
 }
@@ -404,7 +404,7 @@ export const /** number */ FOO = 1;
 reference to an object that has mutable fields or exporting accessor functions for
 mutable data.

 
-
// Bad: both foo and mutateFoo are exported and mutated.
+
// Bad: both foo and mutateFoo are exported and mutated.
 export let /** number */ foo = 0;
 
 /**
@@ -425,7 +425,7 @@ export function setMutateFoo(newMutateFoo) {
 }
 

 
-
// Good: Rather than export the mutable variables foo and mutateFoo directly,
+
// Good: Rather than export the mutable variables foo and mutateFoo directly,
 // instead make them module scoped and export a getter for foo and a wrapper for
 // mutateFooFunc.
 let /** number */ foo = 0;
@@ -453,7 +453,7 @@ export function setMutateFoo(mutateFoo) {
 
export from statements must not be line wrapped and are therefore an
 exception to the 80-column limit. This applies to both export from flavors.

 
-
export {specificName} from './other.js';
+
export {specificName} from './other.js';
 export * from './another.js';
 

 
@@ -463,18 +463,18 @@ export * from './another.js';
 specification allows this. Note that it is possible to create cycles with both
 the import and export statements.

 
-
// a.js
+
// a.js
 import './b.js';
 

 
-
// b.js
+
// b.js
 import './a.js';
 
 // `export from` can cause circular dependencies too!
 export {x} from './c.js';
 

 
-
// c.js
+
// c.js
 import './b.js';
 
 export let x;
@@ -490,7 +490,7 @@ export let x;
 
 
To reference the Closure goog namespace, import Closure's goog.js.

 
-
import * as goog from '../closure/goog/goog.js';
+
import * as goog from '../closure/goog/goog.js';
 
 const name = goog.require('a.name');
 
@@ -508,7 +508,7 @@ used in ES modules.

 require any Closure namespace symbol (i.e., symbols created by goog.provide or
 goog.module) and goog.require will return the value.

 
-
import * as goog from '../closure/goog/goog.js';
+
import * as goog from '../closure/goog/goog.js';
 import * as anEsModule from './anEsModule.js';
 
 const GoogPromise = goog.require('goog.Promise');
@@ -537,7 +537,7 @@ to associate a legacy namespace with an ES module.

 
goog.declareModuleId should only be used to upgrade Closure files to ES
 modules in place, where named exports are used.

 
-
import * as goog from '../closure/goog.js';
+
import * as goog from '../closure/goog.js';
 
 goog.declareModuleId('my.esm');
 
@@ -615,7 +615,7 @@ limit.

 
 
Example:

 
-
// Standard alias style.
+
// Standard alias style.
 const MyClass = goog.require('some.package.MyClass');
 const MyType = goog.requireType('some.package.MyType');
 // Namespace-based alias used to disambiguate.
@@ -643,14 +643,14 @@ goog.require('my.framework.initialization');
 
 
Discouraged:

 
-
// If necessary to disambiguate, prefer PackageClass over SomeClass as it is
+
// If necessary to disambiguate, prefer PackageClass over SomeClass as it is
 // closer to the format of the module name.
 const SomeClass = goog.require('some.package.Class');
 

 
 
Disallowed:

 
-
// Extra terms must come from the namespace.
+
// Extra terms must come from the namespace.
 const MyClassForBizzing = goog.require('some.package.MyClass');
 // Alias must include the entire final namespace component.
 const MyClass = goog.require('some.package.MyClassForBizzing');
@@ -709,7 +709,7 @@ statement.  The first statement of a non-empty block must begin on its own line.
 
 
Disallowed:

 
-
if (someVeryLongCondition())
+
if (someVeryLongCondition())
   doSomething();
 
 for (let i = 0; i < foo.length; i++) bar(foo[i]);
@@ -720,7 +720,7 @@ no wrapping (and that doesn’t have an else) may be kept on a single line w
 braces when it improves readability.  This is the only case in which a control
 structure may omit braces and newlines.

 
-
if (shortCondition()) foo();
+
if (shortCondition()) foo();
 

 
 
4.1.2 Nonempty blocks: K&R style

@@ -740,7 +740,7 @@ there is no line break after the brace if it is followed by else<
 
 
Example:

 
-
class InnerClass {
+
class InnerClass {
   constructor() {}
 
   /** @param {number} foo */
@@ -766,12 +766,12 @@ multiple blocks: if/else or try/cat
 
 
Example:

 
-
function doNothing() {}
+
function doNothing() {}
 

 
 
Disallowed:

 
-
if (condition) {
+
if (condition) {
   // …
 } else if (otherCondition) {} else {
   // …
@@ -795,7 +795,7 @@ block. (See the example in ??).

 construct.” For example, the following are all valid (not an exhaustive
 list):

 
-
const a = [
+
const a = [
   0,
   1,
   2,
@@ -806,7 +806,7 @@ const b =
 
 

 
-
const c = [0, 1, 2];
+
const c = [0, 1, 2];
 
 someMethod(foo, [
   0, 1, 2,
@@ -823,7 +823,7 @@ larger arrays.

 construct.” The same examples apply as ??. For
 example, the following are all valid (not an exhaustive list):

 
-
const a = {
+
const a = {
   a: 0,
   b: 1,
 };
@@ -832,7 +832,7 @@ const b =
     {a: 0, b: 1};
 

 
-
const c = {a: 0, b: 1};
+
const c = {a: 0, b: 1};
 
 someMethod(foo, {
   a: 0, b: 1,
@@ -849,7 +849,7 @@ are still terminated with a semicolon). Use the extends keyword, bu
 
 
Example:

 
-
class Foo {
+
class Foo {
   constructor() {
     /** @type {number} */
     this.x = 42;
@@ -863,7 +863,7 @@ are still terminated with a semicolon). Use the extends keyword, bu
 Foo.Empty = class {};
 

 
-
/** @extends {Foo<string>} */
+
/** @extends {Foo<string>} */
 foo.Bar = class extends Foo {
   /** @override */
   method() {
@@ -886,7 +886,7 @@ indentation depth.

 
 
Example:

 
-
prefix.something.reallyLongFunctionName('whatever', (a1, a2) => {
+
prefix.something.reallyLongFunctionName('whatever', (a1, a2) => {
   // Indent the function body +2 relative to indentation depth
   // of the 'prefix' statement one line above.
   if (a1.equals(a2)) {
@@ -922,7 +922,7 @@ indentation level, as if a block had been closed.

 
 
Example:

 
-
switch (animal) {
+
switch (animal) {
   case Animal.BANDERSNATCH:
     handleBandersnatch();
     break;
@@ -994,14 +994,14 @@ level. 

 
 
Preferred:

 
-
currentEstimate =
+
currentEstimate =
     calc(currentEstimate + x * currentEstimate) /
         2.0;
 

 
 
Discouraged:

 
-
currentEstimate = calc(currentEstimate + x *
+
currentEstimate = calc(currentEstimate + x *
     currentEstimate) / 2.0;
 

 
@@ -1114,7 +1114,7 @@ where it was already used.

 
Here is an example without alignment, followed by one with alignment.  Both are
 allowed, but the latter is discouraged:

 
-
{
+
{
   tiny: 42, // this is great
   longer: 435, // this too
 };
@@ -1138,7 +1138,7 @@ information, slows down reviewers and exacerbates merge conflicts.

 
 
Prefer to put all function arguments on the same line as the function name. If doing so would exceed the 80-column limit, the arguments must be line-wrapped in a readable way. To save space, you may wrap as close to 80 as possible, or put each argument on its own line to enhance readability. Indentation should be four spaces. Aligning to the parenthesis is allowed, but discouraged. Below are the most common patterns for argument wrapping:

 
-
// Arguments start on a new line, indented four spaces. Preferred when the
+
// Arguments start on a new line, indented four spaces. Preferred when the
 // arguments don't fit on the same line with the function name (or the keyword
 // "function") but fit entirely on the second line. Works with very long
 // function names, survives renaming without reindenting, low on space.
@@ -1190,7 +1190,7 @@ be in /* … */ or //-style. For multi-line 
 lines must start with * aligned with the * on the previous line, to make
 comments obvious with no extra context.

 
-
/*
+
/*
  * This is
  * okay.
  */
@@ -1212,13 +1212,13 @@ not sufficiently convey the meaning, and refactoring the method to be clearer is
 infeasible .
 Their preferred format is before the value with =:

 
-
someFunction(obviousParam, /* shouldRender= */ true, /* name= */ 'hello');
+
someFunction(obviousParam, /* shouldRender= */ true, /* name= */ 'hello');
 

 
 
For consistency with surrounding code you may put them after the value without
 =:

 
-
someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */);
+
someFunction(obviousParam, true /* shouldRender */, 'hello' /* name */);
 

 
 
5 Language features

@@ -1253,7 +1253,7 @@ else inline before the variable name if no other JSDoc is present.

 
 
Example:

 
-
const /** !Array<number> */ data = [];
+
const /** !Array<number> */ data = [];
 
 /**
  * Some description.
@@ -1265,7 +1265,7 @@ const data = [];
 
Mixing inline and JSDoc styles is not allowed: the compiler will only process
 the first JsDoc and the inline annotations will be lost.

 
-
/** Some description. */
+
/** Some description. */
 const /** !Array<number> */ data = [];
 

 
@@ -1287,7 +1287,7 @@ element and the closing bracket.

 
 
Example:

 
-
const values = [
+
const values = [
   'first value',
   'second value',
 ];
@@ -1300,7 +1300,7 @@ instead.

 
 
Disallowed:

 
-
const a1 = new Array(x1, x2, x3);
+
const a1 = new Array(x1, x2, x3);
 const a2 = new Array(x1, x2);
 const a3 = new Array(x1);
 const a4 = new Array();
@@ -1313,7 +1313,7 @@ it will be a single-element array.

 
 
Instead, write

 
-
const a1 = [x1, x2, x3];
+
const a1 = [x1, x2, x3];
 const a2 = [x1, x2];
 const a3 = [x1];
 const a4 = [];
@@ -1334,7 +1334,7 @@ destructuring (such as when unpacking multiple values from a single array or
 iterable).  A final rest element may be included (with no space between the
 ... and the variable name). Elements should be omitted if they are unused.

 
-
const [a, b, c, ...rest] = generateResults();
+
const [a, b, c, ...rest] = generateResults();
 let [, b,, d] = someArray;
 

 
@@ -1343,13 +1343,13 @@ name is required but ignored). Always specify [] as the default val
 destructured array parameter is optional, and provide default values on the left
 hand side:

 
-
/** @param {!Array<number>=} param1 */
+
/** @param {!Array<number>=} param1 */
 function optionalDestructuring([a = 4, b = 2] = []) { … };
 

 
 
Disallowed:

 
-
function badDestructuring([a, b] = [4, 2]) { … };
+
function badDestructuring([a, b] = [4, 2]) { … };
 

 
 
Tip: For (un)packing multiple values into a function’s parameter or return,
@@ -1365,7 +1365,7 @@ more awkward constructs with Array.prototype.  There is no space af
 
 
Example:

 
-
[...foo]   // preferred over Array.prototype.slice.call(foo)
+
[...foo]   // preferred over Array.prototype.slice.call(foo)
 [...foo, ...bar]   // preferred over foo.concat(bar)
 

 
@@ -1390,7 +1390,7 @@ types in a single object literal.

 
 
Disallowed:

 
-
{
+
{
   width: 42, // struct-style unquoted key
   'maxWidth': 43, // dict-style quoted key
 }
@@ -1402,7 +1402,7 @@ the compiler cannot rename/obfuscate the string literal.

 
 
Disallowed:

 
-
/** @type {{width: number, maxWidth: (number|undefined)}} */
+
/** @type {{width: number, maxWidth: (number|undefined)}} */
 const o = {width: 42};
 if (o.hasOwnProperty('maxWidth')) {
   ...
@@ -1411,7 +1411,7 @@ if (o.hasOwnProperty('maxWidth')) {
 
 
This is best implemented as:

 
-
/** @type {{width: number, maxWidth: (number|undefined)}} */
+
/** @type {{width: number, maxWidth: (number|undefined)}} */
 const o = {width: 42};
 if (o.maxWidth != null) {
   ...
@@ -1435,7 +1435,7 @@ function literal.

 
 
Example:

 
-
return {
+
return {
   stuff: 'candy',
   method() {
     return this.stuff;  // Returns 'candy'
@@ -1449,7 +1449,7 @@ the object literal.

 
 
Example:

 
-
class {
+
class {
   getObjectLiteral() {
     this.stuff = 'fruit';
     return {
@@ -1466,7 +1466,7 @@ the object literal.

 
 
Example:

 
-
const foo = 1;
+
const foo = 1;
 const bar = 2;
 const obj = {
   foo,
@@ -1492,7 +1492,7 @@ by the compiler).

 
 
Example:

 
-
/**
+
/**
  * @param {string} ordinary
  * @param {{num: (number|undefined), str: (string|undefined)}=} param1
  *     num: The number of times to do something.
@@ -1503,7 +1503,7 @@ function destructured(ordinary, {num, str = 'some default'} = {})
 
 
Disallowed:

 
-
/** @param {{x: {num: (number|undefined), str: (string|undefined)}}} param1 */
+
/** @param {{x: {num: (number|undefined), str: (string|undefined)}}} param1 */
 function nestedTooDeeply({x: {num, str}}) {};
 /** @param {{num: (number|undefined), str: (string|undefined)}=} param1 */
 function nonShorthandProperty({num: a, str: b} = {}) {};
@@ -1523,7 +1523,7 @@ long it is (see ??).

 Additional properties may not be added to an enum after it is defined.  Enums
 must be constant, and all enum values must be deeply immutable.

 
-
/**
+
/**
  * Supported temperature scales.
  * @enum {string}
  */
@@ -1563,7 +1563,7 @@ class' prototype.

 
 
Example:

 
-
class Foo {
+
class Foo {
   constructor() {
     /** @private @const {!Bar} */
     this.bar_ = computeBar();
@@ -1608,7 +1608,7 @@ that doesn’t define the method itself.

 
 
Disallowed:

 
-
class Base { /** @nocollapse */ static foo() {} }
+
class Base { /** @nocollapse */ static foo() {} }
 class Sub extends Base {}
 function callFoo(cls) { cls.foo(); }  // discouraged: don't call static methods dynamically
 Sub.foo();  // Disallowed: don't call static methods on subclasses that don't define it themselves
@@ -1636,7 +1636,7 @@ appropriate.

 
goog.defineClass allows for a class-like definition similar to ES6 class
 syntax:

 
-
let C = goog.defineClass(S, {
+
let C = goog.defineClass(S, {
   /**
    * @param {string} value
    */
@@ -1659,7 +1659,7 @@ syntax:

 
Alternatively, while goog.defineClass should be preferred for all new code,
 more traditional syntax is also allowed.

 
-
/**
+
/**
   * @constructor @extends {S}
   * @param {string} value
   */
@@ -1710,7 +1710,7 @@ the get and set shorthand method keywords or Obj
 
 
Disallowed:

 
-
class Foo {
+
class Foo {
   get next() { return this.nextId++; }
 }
 

@@ -1734,7 +1734,7 @@ be declared as uninitialized members in the class constructor.

 
 
Example:

 
-
/**
+
/**
  * Something that can frobnicate.
  * @record
  */
@@ -1769,13 +1769,13 @@ for more on exports.

 
 
Examples:

 
-
/** @param {string} str */
+
/** @param {string} str */
 exports.processString = (str) => {
   // Process the string.
 };
 

 
-
/** @param {string} str */
+
/** @param {string} str */
 const processString = (str) => {
   // Process the string.
 };
@@ -1821,7 +1821,7 @@ simple expressions).

 
 
Examples:

 
-
/**
+
/**
  * Arrow functions can be documented just like normal functions.
  * @param {number} numParam A number to add.
  * @param {string} strParam Another number to add that happens to be a string.
@@ -1850,7 +1850,7 @@ class CallbackExample {
 
 
Disallowed:

 
-
/**
+
/**
  * A function with no params and no returned value.
  * This single expression body usage is illegal because the program logic does
  * not require returning a value and we're missing the `void` operator.
@@ -1868,7 +1868,7 @@ delegating yields, attach the * to the yield keyword.<
 
 
Example:

 
-
/** @return {!Iterator<number>} */
+
/** @return {!Iterator<number>} */
 function* gen1() {
   yield 42;
 }
@@ -1904,7 +1904,7 @@ methods must omit default parameter values.

 
 
Example:

 
-
/**
+
/**
  * @param {string} required This parameter is always needed.
  * @param {string=} optional This parameter can be omitted.
  * @param {!Node=} node Another optional parameter.
@@ -1946,7 +1946,7 @@ parameter arguments, which confusingly shadows the built-in name.Example:

 
-
/**
+
/**
  * @param {!Array<string>} array This is an ordinary parameter.
  * @param {...number} numbers The remainder of arguments are all numbers.
  */
@@ -1966,7 +1966,7 @@ multiple parameters of a variadic function.  There is no space after the .
 
 
Example:

 
-
function myFunction(...elements) {}
+
function myFunction(...elements) {}
 myFunction(...array, ...iterable, ...generator());
 

 
@@ -1994,7 +1994,7 @@ not matter.

 
 
Example:

 
-
function arithmetic(a, b) {
+
function arithmetic(a, b) {
   return `Here is a table of arithmetic operations:
 ${a} + ${b} = ${a + b}
 ${a} - ${b} = ${a - b}
@@ -2012,14 +2012,14 @@ after the slash, and is less obvious to readers.

 
 
Disallowed:

 
-
const longString = 'This is a very long string that far exceeds the 80 \
+
const longString = 'This is a very long string that far exceeds the 80 \
     column limit. It unfortunately contains long stretches of spaces due \
     to how the continued lines are indented.';
 

 
 
Instead, write

 
-
const longString = 'This is a very long string that far exceeds the 80 ' +
+
const longString = 'This is a very long string that far exceeds the 80 ' +
     'column limit. It does not contain long stretches of spaces since ' +
     'the concatenated strings are cleaner.';
 

@@ -2068,7 +2068,7 @@ property).

 it truly is appropriate to take no action whatsoever in a catch block, the
 reason this is justified is explained in a comment.

 
-
try {
+
try {
   return handleNumericResponse(response);
 } catch (ok) {
   // it's not numeric; that's fine, just continue
@@ -2078,7 +2078,7 @@ return handleTextResponse(response);
 
 
Disallowed:

 
-
  try {
+
  try {
     shouldFail();
     fail('expected an error');
   } catch (expected) {
@@ -2103,7 +2103,7 @@ statement group of the switch block.

 
 
Example:

 
-
switch (input) {
+
switch (input) {
   case 1:
   case 2:
     prepareOneOrTwo();
@@ -2138,7 +2138,7 @@ target of an event, or unnecessarily call()ed or apply()Catching both null and undefined values:

 
-
if (someObjectOrPrimitive == null) {
+
if (someObjectOrPrimitive == null) {
   // Checking for null catches both null and undefined for objects and
   // primitives, but does not catch other falsy values like 0 or the empty
   // string.
@@ -2182,7 +2182,7 @@ forbidden.

 
 
Disallowed:

 
-
const /** Boolean */ x = new Boolean(false);
+
const /** Boolean */ x = new Boolean(false);
 if (x) alert(typeof x);  // alerts 'object' - WAT?
 

 
@@ -2191,7 +2191,7 @@ using + or concatenating the empty string) or creating symbols.

 
 
Example:

 
-
const /** boolean */ x = Boolean(0);
+
const /** boolean */ x = Boolean(0);
 if (!x) alert(typeof x);  // alerts 'boolean', as expected
 

 
@@ -2211,18 +2211,18 @@ possible; nothing else may modify builtin objects.

 
 
Disallowed:

 
-
new Foo;
+
new Foo;
 

 
 
Use instead:

 
-
new Foo();
+
new Foo();
 

 
 
Omitting parentheses can lead to subtle mistakes. These two lines are not
 equivalent:

 
-
new Foo().Bar();
+
new Foo().Bar();
 new Foo.Bar();
 

 
@@ -2240,7 +2240,7 @@ understandable by a new reader. Do not use abbreviations that are ambiguous or
 unfamiliar to readers outside your project, and do not abbreviate by deleting
 letters within a word.

 
-
errorCount          // No abbreviation.
+
errorCount          // No abbreviation.
 dnsConnectionIndex  // Most people know what "DNS" stands for.
 referrerUrl         // Ditto for "URL".
 customerId          // "Id" is both ubiquitous and unlikely to be misunderstood.
@@ -2248,7 +2248,7 @@ customerId          // "Id" is both ubiquitous and unlikely to be misunderstood.
 
 
Disallowed:

 
-
n                   // Meaningless.
+
n                   // Meaningless.
 nErr                // Ambiguous abbreviation.
 nCompConns          // Ambiguous abbreviation.
 wgcConnections      // Only your group knows what this stands for.
@@ -2313,7 +2313,7 @@ intending to never mutate the object is generally not enough.

 
 
Examples:

 
-
// Constants
+
// Constants
 const NUMBER = 5;
 /** @const */ exports.NAMES = ImmutableList.of('Ed', 'Ann');
 /** @enum */ exports.SomeEnum = { ENUM_CONSTANT: 'value' };
@@ -2339,7 +2339,7 @@ Aliases may also be used within functions.  Aliases must be const.<
 
 
Examples:

 
-
const staticHelper = importedNamespace.staticHelper;
+
const staticHelper = importedNamespace.staticHelper;
 const CONSTANT_NAME = ImportedClass.CONSTANT_NAME;
 const {assert, assertInstanceof} = asserts;
 

@@ -2465,7 +2465,7 @@ character of:
 
 
The basic formatting of JSDoc blocks is as seen in this example:

 
-
/**
+
/**
  * Multiple lines of JSDoc text are written here,
  * wrapped normally.
  * @param {number} arg A number to do something to.
@@ -2475,7 +2475,7 @@ function doSomething(arg) { … }
 
 
or in this single-line example:

 
-
/** @const @private {!Foo} A short bit of JSDoc. */
+
/** @const @private {!Foo} A short bit of JSDoc. */
 this.foo_ = foo;
 

 
@@ -2492,7 +2492,7 @@ optimization.  As such, these comments must be well-formed.

 
Note that tools that automatically extract JSDoc (e.g. JsDossier) will often
 ignore plain text formatting, so if you did this:

 
-
/**
+
/**
  * Computes weight based on three factors:
  *   items sent
  *   items received
@@ -2507,7 +2507,7 @@ ignore plain text formatting, so if you did this:

 
 
Instead, write a Markdown list:

 
-
/**
+
/**
  * Computes weight based on three factors:
  *
  *  - items sent
@@ -2524,7 +2524,7 @@ occupy their own line, with the tag at the beginning of the line.

 
 
Disallowed:

 
-
/**
+
/**
  * The "param" tag must occupy its own line and may not be combined.
  * @param {number} left @param {number} right
  */
@@ -2535,7 +2535,7 @@ function add(left, right) { ... }
 @const, @final, @export) may be combined onto the same line, along with an
 optional type when appropriate.

 
-
/**
+
/**
  * Place more complex annotations (like "implements" and "template")
  * on their own lines.  Multiple simple tags (like "export" and "final")
  * may be combined in one line.
@@ -2568,7 +2568,7 @@ System.

 be lined up with the description on previous lines, but this horizontal
 alignment is discouraged.

 
-
/**
+
/**
  * Illustrates line wrapping for long param/return descriptions.
  * @param {string} foo This is a param with a description too long to fit in
  *     one line.
@@ -2593,7 +2593,7 @@ dependencies or compatibility information. Wrapped lines are not indented.

 
 
Example:

 
-
/**
+
/**
  * @fileoverview Description of file, its uses and information
  * about its dependencies.
  * @package
@@ -2611,7 +2611,7 @@ constructor. @constructor and @extends annotations are
 class keyword unless the class is being used to declare an @interface or
 it extends a generic class.

 
-
/**
+
/**
  * A fancier event target that does cool things.
  * @implements {Iterable<string>}
  */
@@ -2644,7 +2644,7 @@ class Listable {
 also have a description. Individual enum items may be documented with a JSDoc
 comment on the preceding line.

 
-
/**
+
/**
  * A useful type union, which is reused often.
  * @typedef {!Bandersnatch|!BandersnatchType}
  */
@@ -2690,7 +2690,7 @@ class method (including visibility annotations) and they should be omitted in
 the overridden method. However, if any type is refined in type annotations, all
 @param and @return annotations must be specified explicitly.

 
-
/** A class that does something. */
+
/** A class that does something. */
 class SomeClass extends SomeBaseClass {
   /**
    * Operates on an instance of MyClass and returns something.
@@ -2719,13 +2719,13 @@ function makeArray(arg) { ... }
 optionally use inline JSDocs in the function's signature. These inline JSDocs
 specify the return and param types without tags.

 
-
function /** string */ foo(/** number */ arg) {...}
+
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.

 
-
class MyClass {
+
class MyClass {
   /**
    * @param {number} arg
    * @return {string}
@@ -2734,7 +2734,7 @@ For example, methods which return values need a @return tag.

 }
 

 
-
// Illegal inline JSDocs.
+
// Illegal inline JSDocs.
 
 class MyClass {
   /** @return {string} */ foo() {...}
@@ -2749,7 +2749,7 @@ class MyClass {
 inference is insufficient or explicit annotation improves readability, then
 annotate param and return types like this:

 
-
promise.then(
+
promise.then(
     /** @return {string} */
     (/** !Array<string> */ items) => {
       doSomethingWith(items);
@@ -2767,7 +2767,7 @@ code.

 
 
Publicly exported constants are commented the same way as properties.

 
-
/** My class. */
+
/** My class. */
 class MyClass {
   /** @param {string=} someString */
   constructor(someString = 'default string') {
@@ -2821,7 +2821,7 @@ use sites.
 
 
Bad:

 
-
const /** MyObject */ myObject = null; // Non-primitive types must be annotated.
+
const /** MyObject */ myObject = null; // Non-primitive types must be annotated.
 const /** !number */ someNum = 5; // Primitives are non-nullable by default.
 const /** number? */ someNullableNum = null; // ? should precede the type.
 const /** !{foo: string, bar: number} */ record = ...; // Already non-nullable.
@@ -2834,7 +2834,7 @@ const /** SomeCamelCaseName */ n = ...;
 
 
Good:

 
-
const /** ?MyObject */ myObject = null;
+
const /** ?MyObject */ myObject = null;
 const /** number */ someNum = 5;
 const /** ?number */ someNullableNum = null;
 const /** {foo: string, bar: number} */ record = ...;
@@ -2851,7 +2851,7 @@ cannot remedy it , it is possible to
 tighten the type by adding a type annotation comment and enclosing the
 expression in parentheses. Note that the parentheses are required.

 
-
/** @type {number} */ (x)
+
/** @type {number} */ (x)
 

 
 
7.10.3 Template Parameter Types

@@ -2861,14 +2861,14 @@ makes it easier for readers to understand what code does.

 
 
Bad:

 
-
const /** !Object */ users = {};
+
const /** !Object */ users = {};
 const /** !Array */ books = [];
 const /** !Promise */ response = ...;
 

 
 
Good:

 
-
const /** !Object<string, !User> */ users = {};
+
const /** !Object<string, !User> */ users = {};
 const /** !Array<string> */ books = [];
 const /** !Promise<!Response> */ response = ...;
 
@@ -2898,7 +2898,7 @@ function jsdoc appears above the whole assignment expression).

 or @return. Use it also for variables or properties of function type, if they
 are not immediately initialized with the function definition.

 
-
  /** @private {function(string): string} */
+
  /** @private {function(string): string} */
   this.idGenerator_ = googFunctions.identity;
 

 
@@ -2908,7 +2908,7 @@ strange and unexpected behavior, and is rarely what is actually desired.

 
 
Bad - type error, but no warning given:

 
-
/** @param {function()} generateNumber */
+
/** @param {function()} generateNumber */
 function foo(generateNumber) {
   const /** number */ x = generateNumber();  // No compile-time type error here.
 }
@@ -2918,7 +2918,7 @@ foo(() => 'clearly not a number');
 
 
Good:

 
-
/**
+
/**
  * @param {function(): *} inputFunction1 Can return any type.
  * @param {function(): undefined} inputFunction2 Definitely doesn't return
  *      anything.
@@ -2938,7 +2938,7 @@ annotations.

 
 
Good:

 
-
/** @type {function(string): number} */
+
/** @type {function(string): number} */
 
 /** @type {{foo: number, bar: number}} */
 
@@ -2962,7 +2962,7 @@ annotations.

 
 
Bad:

 
-
// Only put a space after the colon
+
// Only put a space after the colon
 /** @type {function(string) : number} */
 
 // Put spaces after colons and commas
@@ -3023,7 +3023,7 @@ it can be taken care of properly.
 
 
Example

 
-
/** @suppress {uselessCode} Unrecognized 'use asm' declaration */
+
/** @suppress {uselessCode} Unrecognized 'use asm' declaration */
 function fn() {
   'use asm';
   return 0;
@@ -3124,7 +3124,7 @@ part of valid Google style.

 
 
Syntax: @author username@google.com (First Last)

 
-
/**
+
/**
  * @fileoverview Utilities for handling textareas.
  * @author kuth@google.com (Uthur Pendragon)
  */
@@ -3142,7 +3142,7 @@ to determine who owns the test results.

 
 
Syntax: @bug bugnumber

 
-
/** @bug 1234567 */
+
/** @bug 1234567 */
 function testSomething() {
   // …
 }
@@ -3174,7 +3174,7 @@ regression tests as easy as possible.

 
Historically, `BatchItem` was written as
 {@code BatchItem}.

 
-
/** Processes pending `BatchItem` instances. */
+
/** Processes pending `BatchItem` instances. */
 function processBatchItems() {}
 

 
@@ -3189,7 +3189,7 @@ formatted in generated documentation.

 
 
Syntax: @desc Message description

 
-
/** @desc Notifying a user that their account has been created. */
+
/** @desc Notifying a user that their account has been created. */
 exports.MSG_ACCOUNT_CREATED = goog.getMsg(
     'Your account has been successfully created.');
 

@@ -3205,7 +3205,7 @@ exports.MSG_ACCOUNT_CREATED = goog.getMsg(
 
This tag is used to generate cross-reference links within generated
 documentation.

 
-
/** Processes pending {@link BatchItem} instances. */
+
/** Processes pending {@link BatchItem} instances. */
 function processBatchItems() {}
 

 
@@ -3213,7 +3213,7 @@ function processBatchItems() {}
 generated documentation. For external links, always use Markdown's link syntax
 instead:

 
-
/**
+
/**
  * This class implements a useful subset of the
  * [native Event interface](https://dom.spec.whatwg.org/#event).
  */
@@ -3228,7 +3228,7 @@ class ApplicationEvent {}
 
 
Syntax: @see Link

 
-
/**
+
/**
  * Adds a single item, recklessly.
  * @see #addSafely
  * @see goog.Collect
@@ -3246,7 +3246,7 @@ class ApplicationEvent {}
 
 
Syntax: @supported Description

 
-
/**
+
/**
  * @fileoverview Event Manager
  * Provides an abstracted interface to the browsers' event systems.
  * @supported IE10+, Chrome, Safari
@@ -3413,7 +3413,7 @@ function, script or module, which can cause unexpected behavior, especially with
 function closures that reference var declarations inside of loops. The
 following code gives an example:

 
-
for (var i = 0; i < 3; ++i) {
+
for (var i = 0; i < 3; ++i) {
   var iteration = i;
   setTimeout(function() { console.log(iteration); }, i*1000);
 }
@@ -3430,7 +3430,7 @@ function, var declarations should be as close as possible to their
 for readability purposes. However, do not put a var declaration inside a block
 if that variable is referenced outside the block. For example:

 
-
function sillyFunction() {
+
function sillyFunction() {
   var count = 0;
   for (var x in y) {
     // "count" could be declared here, but don't do that.
@@ -3450,7 +3450,7 @@ for local variables).

 
 
Do not do this:

 
-
if (x) {
+
if (x) {
   function foo() {}
 }
 

@@ -3465,7 +3465,7 @@ explicitly ban them in block scopes in strict mode.

 
To get consistent behavior, instead use a var initialized with a function
 expression to define a function within a block:

 
-
if (x) {
+
if (x) {
   var foo = function() {};
 }
 

@@ -3498,7 +3498,7 @@ exceed the 80 column line length limit.

 
 
The lines should be sorted alphabetically, with uppercase letters coming first:

 
-
goog.provide('namespace.MyClass');
+
goog.provide('namespace.MyClass');
 goog.provide('namespace.helperFoo');
 
 goog.require('an.extremelyLongNamespace.thatSomeoneThought.wouldBeNice.andNowItIsLonger.Than80Columns');
@@ -3515,12 +3515,12 @@ the same class (e.g. enums, inner classes, etc).

 
 
Do this:

 
-
goog.provide('namespace.MyClass');
+
goog.provide('namespace.MyClass');
 

 
 
Not this:

 
-
goog.provide('namespace.MyClass');
+
goog.provide('namespace.MyClass');
 goog.provide('namespace.MyClass.CONSTANT');
 goog.provide('namespace.MyClass.Enum');
 goog.provide('namespace.MyClass.InnerClass');
@@ -3530,7 +3530,7 @@ goog.provide('namespace.MyClass.staticMethod');
 
 
Members on namespaces may also be provided:

 
-
goog.provide('foo.bar');
+
goog.provide('foo.bar');
 goog.provide('foo.bar.CONSTANT');
 goog.provide('foo.bar.method');
 

@@ -3559,7 +3559,7 @@ Instead, continue from the 0 column.

 (e.g., most constructors, enums, and namespaces). Do not do this (see below for
 how to alias a constructor):

 
-
goog.scope(function() {
+
goog.scope(function() {
 var Button = goog.ui.Button;
 
 Button = function() { ... };
@@ -3568,7 +3568,7 @@ Button = function() { ... };
 
 
Names must be the same as the last property of the global that they are aliasing.

 
-
goog.provide('my.module.SomeType');
+
goog.provide('my.module.SomeType');
 
 goog.require('goog.dom');
 goog.require('goog.ui.Button');