Add namespace and alias annotations to jsdoc (#5550)

* Add annotations to files under core/events

* Add annotations to files under core/interfaces

* Add annotations to files under core/keyboard_nav

* Add annotations to files under core/renderers

* Add annotations to files under core/serialization

* Add annotations to files under core/theme

* Add annotations to files under core/toolbox

* Add annotations to files under core/utils

* Add annotations to files under core

core/utils/aria.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.aria
- * @namespace
+ * ARIA-related constants and utilities.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.aria
  */
 goog.module('Blockly.utils.aria');
 

core/utils/colour.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.colour
- * @namespace
+ * Utility methods for colour manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.colour
  */
 goog.module('Blockly.utils.colour');
 

core/utils/coordinate.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.Coordinate
- * @namespace
+ * Utility methods for coordinate manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.Coordinate
  */
 goog.module('Blockly.utils.Coordinate');
 
@@ -24,6 +26,7 @@ goog.module('Blockly.utils.Coordinate');
  * @param {number} y Top.
  * @struct
  * @constructor
+ * @alias Blockly.utils.Coordinate
  */
 const Coordinate = function(x, y) {
   /**

core/utils/deprecation.js

@@ -12,8 +12,9 @@
 'use strict';
 
 /**
- * @name Blockly.utils.deprecation
- * @namespace
+ * Helper function for warning developers about deprecations.
+ * This method is not specific to Blockly.
+ * @namespace Blockly.utils.deprecation
  */
 goog.module('Blockly.utils.deprecation');
 

core/utils/dom.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.dom
- * @namespace
+ * Utility methods for DOM manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.dom
  */
 goog.module('Blockly.utils.dom');
 

core/utils/global.js

@@ -10,6 +10,10 @@
  */
 'use strict';
 
+/**
+ * Provides a reference to the global object.
+ * @namespace Blockly.utils.global
+ */
 goog.module('Blockly.utils.global');
 
 

core/utils/idgenerator.js

@@ -11,8 +11,8 @@
 'use strict';
 
 /**
- * @name Blockly.utils.idGenerator
- * @namespace
+ * Generators for unique IDs.
+ * @namespace Blockly.utils.idGenerator
  */
 goog.module('Blockly.utils.idGenerator');
 
@@ -20,6 +20,7 @@ goog.module('Blockly.utils.idGenerator');
 /**
  * Namespace object for internal implementations we want to be able to
  * stub in tests.
+ * @ignore
  */
 const internal = {};
 exports.TEST_ONLY = internal;

core/utils/keycodes.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.KeyCodes
- * @namespace
+ * Constant declarations for common key codes.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.KeyCodes
  */
 goog.module('Blockly.utils.KeyCodes');
 

core/utils/math.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.math
- * @namespace
+ * Utility methods for math.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.math
  */
 goog.module('Blockly.utils.math');
 

core/utils/metrics.js

@@ -11,14 +11,15 @@
 'use strict';
 
 /**
- * @name Blockly.utils.Metrics
- * @namespace
+ * Workspace metrics definitions.
+ * @namespace Blockly.utils.Metrics
  */
 goog.module('Blockly.utils.Metrics');
 
 
 /**
  * @record
+ * @alias Blockly.utils.Metrics
  */
 const Metrics = function() {};
 

core/utils/object.js

@@ -11,8 +11,8 @@
 'use strict';
 
 /**
- * @name Blockly.utils.object
- * @namespace
+ * Utility methods for objects.
+ * @namespace Blockly.utils.object
  */
 goog.module('Blockly.utils.object');
 

core/utils/rect.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.Rect
- * @namespace
+ * Utility methods for rectangle manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.Rect
  */
 goog.module('Blockly.utils.Rect');
 
@@ -27,6 +29,7 @@ goog.module('Blockly.utils.Rect');
  * @param {number} right Right.
  * @struct
  * @constructor
+ * @alias Blockly.utils.Rect
  */
 const Rect = function(top, bottom, left, right) {
   /** @type {number} */

core/utils/size.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Size
- * @namespace
+ * Utility methods for size calculation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.Size
  */
 goog.module('Blockly.utils.Size');
 
@@ -25,6 +27,7 @@ goog.module('Blockly.utils.Size');
  * @param {number} height Height.
  * @struct
  * @constructor
+ * @alias Blockly.utils.Size
  */
 const Size = function(width, height) {
   /**

core/utils/string.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.string
- * @namespace
+ * Utility methods for string manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.string
  */
 goog.module('Blockly.utils.string');
 

core/utils/style.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.style
- * @namespace
+ * Utilities for element styles.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.style
  */
 goog.module('Blockly.utils.style');
 

core/utils/svg.js

@@ -12,8 +12,9 @@
 'use strict';
 
 /**
- * @name Svg
- * @namespace
+ * Defines the Svg class. Its constants enumerate
+ * all SVG tag names used by Blockly.
+ * @namespace Blockly.utils.Svg
  */
 goog.module('Blockly.utils.Svg');
 
@@ -24,6 +25,7 @@ goog.module('Blockly.utils.Svg');
  * @constructor
  * @template T
  * @private
+ * @alias Blockly.utils.Svg
  */
 const Svg = function(tagName) {
   /**

core/utils/svg_paths.js

@@ -12,8 +12,8 @@
 'use strict';
 
 /**
- * @name Blockly.utils.svgPaths
- * @namespace
+ * Methods for creating parts of SVG path strings.  See
+ * @namespace Blockly.utils.svgPaths
  */
 goog.module('Blockly.utils.svgPaths');
 

core/utils/toolbox.js

@@ -11,8 +11,8 @@
 'use strict';
 
 /**
- * @name Blockly.utils.toolbox
- * @namespace
+ * Utility functions for the toolbox and flyout.
+ * @namespace Blockly.utils.toolbox
  */
 goog.module('Blockly.utils.toolbox');
 

core/utils/useragent.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.userAgent
- * @namespace
+ * Useragent detection.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.userAgent
  */
 goog.module('Blockly.utils.userAgent');
 

core/utils/xml.js

@@ -13,8 +13,10 @@
 'use strict';
 
 /**
- * @name Blockly.utils.xml
- * @namespace
+ * XML element manipulation.
+ * These methods are not specific to Blockly, and could be factored out into
+ * a JavaScript framework such as Closure.
+ * @namespace Blockly.utils.xml
  */
 goog.module('Blockly.utils.xml');