From e24784529eda31f48000469e16eb5aeaa5534a86 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <mike@mikegerwitz.com>
Date: Tue, 13 Dec 2011 21:19:14 -0500
Subject: [PATCH] Resolved majority of Closure Compiler warnings (VERBOSE) -
 Ignored warnings from tests for now - VERBOSE flag removed from Makefile for
 now until I can figure out how to   resolve certain warnings

---
 Makefile                               |  1 -
 README.todo                            |  6 +++
 lib/ClassBuilder.js                    | 65 ++++++++++++++++-------
 lib/FallbackVisibilityObjectFactory.js |  3 +-
 lib/MemberBuilder.js                   | 72 ++++++++++++++------------
 lib/MethodWrapperFactory.js            | 14 ++---
 lib/VisibilityObjectFactory.js         |  9 +++-
 lib/VisibilityObjectFactoryFactory.js  |  4 ++
 lib/class.js                           | 41 ++++++++-------
 lib/class_abstract.js                  |  6 +--
 lib/class_final.js                     |  6 +--
 lib/interface.js                       | 16 +++---
 lib/util.js                            | 64 +++++++++++++----------
 lib/warn.js                            |  4 +-
 tools/combine.tpl                      |  4 +-
 tools/externs.js                       |  4 ++
 tools/mkexterns                        | 14 +++--
 17 files changed, 206 insertions(+), 127 deletions(-)
 create mode 100644 tools/externs.js

diff --git a/Makefile b/Makefile
index 8219079..59a56f2 100644
--- a/Makefile
+++ b/Makefile
@@ -70,7 +70,6 @@ build/%.min.js: build/%.js $(path_tools)/externs-global.js  $(path_externs_inter
 	$(compiler)
 	cat $(path_tools)/license.tpl > $@
 	java -jar $(compiler) \
-		--warning_level VERBOSE \
 		--externs $(path_tools)/externs-global.js \
 		--externs $(path_build)/externs-internal.js \
 		--js $< >> $@ || rm $@
diff --git a/README.todo b/README.todo
index c5d25ec..7bd8712 100644
--- a/README.todo
+++ b/README.todo
@@ -41,3 +41,9 @@ PERFORMANCE TESTS
 Performance tests need to be written for every aspect of the system. They will
 ultimately be graphed to show the relative performance across versions of the
 software.
+
+
+CLOSURE COMPILER WARNINGS
+-------------------------
+Certain warnings are suppressed. Figure out the best way to resolve them without
+suppressing them, unless suppression is truely the best option.
diff --git a/lib/ClassBuilder.js b/lib/ClassBuilder.js
index 019a3a5..868c384 100644
--- a/lib/ClassBuilder.js
+++ b/lib/ClassBuilder.js
@@ -80,8 +80,10 @@ var util    = require( __dirname + '/util' ),
  *
  * @param  {Object}  member_builder  member builder
  *
- * @param  {VisibilityObjectFacotry}  visibility_factory  visibility object
+ * @param  {VisibilityObjectFactory}  visibility_factory  visibility object
  *                                                        generator
+ *
+ * @constructor
  */
 module.exports = exports =
 function ClassBuilder( member_builder, visibility_factory )
@@ -89,7 +91,8 @@ function ClassBuilder( member_builder, visibility_factory )
     // allow ommitting the 'new' keyword
     if ( !( this instanceof exports ) )
     {
-        return new exports( member_builder, visibility_factory );
+        // module.exports for Closure Compiler
+        return new module.exports( member_builder, visibility_factory );
     }
 
     /**
@@ -202,9 +205,9 @@ exports.getForcedPublicMethods = function()
  * Since a reference is returned (rather than a copy), the returned object can
  * be modified to alter the metadata.
  *
- * @param  {Class}  cls  class from which to retrieve metadata
+ * @param  {Function|Object}  cls  class from which to retrieve metadata
  *
- * @return  {Object}
+ * @return  {__class_meta}
  */
 exports.getMeta = function( cls )
 {
@@ -278,9 +281,12 @@ exports.isInstanceOf = function( type, instance )
  * The class to inherit from (the first argument) is optional. If omitted, the
  * first argument will be considered to be the properties list.
  *
- * @return  {Object}  extended class
+ * @param  {Function|Object}  _   parent or definition object
+ * @param  {Object=}          __  definition object if parent was provided
+ *
+ * @return  {Function}  extended class
  */
-exports.prototype.build = function extend()
+exports.prototype.build = function extend( _, __ )
 {
     // ensure we'll be permitted to instantiate abstract classes for the base
     this._extending = true;
@@ -374,7 +380,7 @@ exports.prototype.build = function extend()
     var new_class = this.createCtor( cname, abstract_methods, members );
 
     // closure to hold static initialization to be used later by subtypes
-    initStaticVisibilityObj( new_class, static_members );
+    initStaticVisibilityObj( new_class );
     var staticInit = function( ctor, inheriting )
     {
         attachStatic( ctor, static_members, base, inheriting );
@@ -524,7 +530,7 @@ exports.prototype.buildMembers = function buildMembers(
  *
  * @param  {function()}  ctor              class
  * @param  {string}      cname             class name
- * @param  {Object}      abstract_methods
+ * @param  {{__length}}  abstract_methods  object containing abstract methods
  *
  * @return  {undefined}
  */
@@ -596,9 +602,18 @@ exports.prototype.createConcreteCtor = function( cname, members )
     var args  = null,
         _self = this;
 
-    // constructor function to be returned (the name is set to ClassInstance
-    // because some debuggers (e.g. v8) will show the name of this function for
-    // constructor instances rather than invoking the toString() method)
+    /**
+     * Constructor function to be returned
+     *
+     * The name is set to ClassInstance because some debuggers (e.g. v8) will
+     * show the name of this function for constructor instances rather than
+     * invoking the toString() method
+     *
+     * @constructor
+     *
+     * Suppressing due to complaints for using __initProps
+     * @suppress {checkTypes}
+     */
     function ClassInstance()
     {
         if ( !( this instanceof ClassInstance ) )
@@ -790,7 +805,7 @@ exports.prototype._attachPropInit = function(
  *
  * @param {Object} keywords keywords to scan
  *
- * @return {bool} true if to be static, otherwise false
+ * @return {boolean} true if to be static, otherwise false
  */
 function keywordStatic( keywords )
 {
@@ -804,7 +819,7 @@ function keywordStatic( keywords )
 /**
  * Creates and populates the static visibility object
  *
- * @param  {function()}  class
+ * @param  {Function}  ctor  class
  *
  * @return  {undefined}
  */
@@ -812,8 +827,12 @@ function initStaticVisibilityObj( ctor )
 {
     var _self = this;
 
-    // the object will simply be another layer in the prototype chain to
-    // prevent protected/private members from being mixed in with the public
+    /**
+     * the object will simply be another layer in the prototype chain to
+     * prevent protected/private members from being mixed in with the public
+     *
+     * @constructor
+     */
     var sobj = function() {};
     sobj.prototype = ctor;
 
@@ -969,10 +988,13 @@ function attachStatic( ctor, members, base, inheriting )
 /**
  * Initializes class metadata for the given class
  *
- * @param  {Class}  func     class to initialize metadata for
- * @param  {Class}  cparent  class parent
+ * @param  {Function}  func     class to initialize metadata for
+ * @param  {Function}  cparent  class parent
  *
  * @return  {undefined}
+ *
+ * Suppressed due to warnings for use of __cid
+ * @suppress {checkTypes}
  */
 function createMeta( func, cparent )
 {
@@ -1046,6 +1068,7 @@ function attachInstanceId( instance, iid )
  */
 function initInstance( instance )
 {
+    /** @constructor */
     var prot = function() {};
     prot.prototype = instance;
 
@@ -1093,6 +1116,8 @@ function attachInstanceOf( instance )
  * @param  {number}      cid   class id
  *
  * @return  {Object|null}  instance object if found, otherwise null
+ *
+ * @suppress {checkTypes}
  */
 exports.getMethodInstance = function( inst, cid )
 {
@@ -1122,7 +1147,7 @@ function attachAbstract( func, methods )
      * Returns whether the class contains abstract methods (and is therefore
      * abstract)
      *
-     * @return  {Boolean}  true if class is abstract, otherwise false
+     * @return  {boolean}  true if class is abstract, otherwise false
      */
     util.defineSecureProp( func, 'isAbstract', function()
     {
@@ -1153,8 +1178,8 @@ function attachId( ctor, id )
 /**
  * Sets class flags
  *
- * @param  {Class}   ctor   class to flag
- * @param  {Object}  props  class properties
+ * @param  {Function}  ctor   class to flag
+ * @param  {Object}   props  class properties
  *
  * @return  {undefined}
  */
diff --git a/lib/FallbackVisibilityObjectFactory.js b/lib/FallbackVisibilityObjectFactory.js
index cf232ae..b8f5f09 100644
--- a/lib/FallbackVisibilityObjectFactory.js
+++ b/lib/FallbackVisibilityObjectFactory.js
@@ -35,7 +35,8 @@ module.exports = exports = function FallbackVisibilityObjectFactory()
     // permit omitting 'new' keyword
     if ( !( this instanceof exports ) )
     {
-        return new exports();
+        // module.exports for Closure Compiler
+        return new module.exports();
     }
 };
 
diff --git a/lib/MemberBuilder.js b/lib/MemberBuilder.js
index 62e2318..6f6a0d2 100644
--- a/lib/MemberBuilder.js
+++ b/lib/MemberBuilder.js
@@ -39,6 +39,12 @@ var util       = require( __dirname + '/util' ),
 
 /**
  * Responsible for building class members
+ *
+ * @param  {Function}                wrap_method    method wrapper
+ * @param  {Function}                wrap_override  method override wrapper
+ * @param  {MemberBuilderValidator}  validate       member validator
+ *
+ * @constructor
  */
 module.exports = function MemberBuilder( wrap_method, wrap_override, validate )
 {
@@ -69,7 +75,7 @@ exports = module.exports.prototype;
  * @param  {Object}  mprotected  default protected members
  * @param  {Object}  mprivate    default private members
  *
- * @return  {{public: Object, protected: Object, private: Object}}
+ * @return  {__visobj}
  */
 exports.initMembers = function( mpublic, mprotected, mprivate )
 {
@@ -85,17 +91,18 @@ exports.initMembers = function( mpublic, mprotected, mprivate )
  * Copies a method to the appropriate member prototype, depending on
  * visibility, and assigns necessary metadata from keywords
  *
- * @param  {{public: Object, protected: Object, private: Object}} members
+ * @param  {__visobj}  members
+ * @param  {!Object}   meta     metadata container
+ * @param  {string}    name     property name
+ * @param  {*}         value    property value
  *
- * @param  {Object}  meta   metadata container
- * @param  {string}  name   property name
- * @param  {*}       value  property value
+ * @param  {!Object.<boolean>}  keywords  parsed keywords
  *
- * @param  {Object.<string,boolean>}  keywords  parsed keywords
-
- * @param  {Object=}  instCallback  function to call in order to retrieve
- *                                  object to bind 'this' keyword to
- * @param  {number}   cid           class id
+ * @param  {Function}  instCallback  function to call in order to retrieve
+ *                                   object to bind 'this' keyword to
+ *
+ * @param  {number}   cid   class id
+ * @param  {Object=}  base  optional base object to scan
  *
  * @return  {undefined}
  */
@@ -157,14 +164,13 @@ exports.buildMethod = function(
  * Copies a property to the appropriate member prototype, depending on
  * visibility, and assigns necessary metadata from keywords
  *
- * @param  {{public: Object, protected: Object, private: Object}} members
+ * @param  {__visobj}  members
+ * @param  {!Object}   meta     metadata container
+ * @param  {string}    name     property name
+ * @param  {*}         value    property value
  *
- * @param  {Object}  meta   metadata container
- * @param  {string}  name   property name
- * @param  {*}       value  property value
+ * @param  {!Object.<boolean>}  keywords  parsed keywords
  *
- * @param  {Object.<string,boolean>}  keywords  parsed keywords
-
  * @param  {Object=}  base  optional base object to scan
  *
  * @return  {undefined}
@@ -190,18 +196,20 @@ exports.buildProp = function( members, meta, name, value, keywords, base )
  * Copies a getter/setter to the appropriate member prototype, depending on
  * visibility, and assigns necessary metadata from keywords
  *
- * @param  {{public: Object, protected: Object, private: Object}} members
+ * @param  {!__visobj}  members
+ * @param  {!Object}    meta     metadata container
+ * @param  {string}     name     getter name
+ * @param  {*}          get      getter value
+ * @param  {*}          set      setter value
  *
- * @param  {Object}  meta  metadata container
- * @param  {string}  name  getter name
- * @param  {*}       get   getter value
- * @param  {*}       set   setter value
- *
- * @param  {Object.<string,boolean>}  keywords  parsed keywords
+ * @param  {!Object.<boolean>}  keywords  parsed keywords
  *
  * @param  {Object=}  base  optional base object to scan
  *
  * @return  {undefined}
+ *
+ * Closure Compiler is improperly throwing warnings on Object.defineProperty():
+ * @suppress {checkTypes}
  */
 exports.buildGetterSetter = function(
     members, meta, name, get, set, keywords, base
@@ -238,10 +246,10 @@ exports.buildGetterSetter = function(
  *
  * Will throw an exception if multiple access modifiers were used.
  *
- * @param  {{public: Object, protected: Object, private: Object}} members
+ * @param  {__visobj} members
  *
- * @param  {Object.<string,boolean>}  keywords  parsed keywords
- * @param  {string}                   name      member name
+ * @param  {!Object.<boolean>}  keywords  parsed keywords
+ * @param  {string}             name      member name
  *
  * @return  {Object}  reference to visibility of members argument to use
  */
@@ -280,13 +288,12 @@ function getMemberVisibility( members, keywords, name )
 /**
  * Scan each level of visibility for the requested member
  *
- * @param  {{public: Object, protected: Object, private: Object}} members
+ * @param  {__visobj} members
  *
  * @param  {string}   name  member to locate
  * @param  {Object=}  base  optional base object to scan
  *
- * @return  {Object}  Array of member and number corresponding to visibility,
- *                    level if located, otherwise an empty object
+ * @return  {{get,set,member}|null}
  */
 function scanMembers( members, name, base )
 {
@@ -358,9 +365,10 @@ function hideMethod( super_method, new_method, instCallback, cid )
  * @param  {function()}  super_method      method to override
  * @param  {function()}  new_method        method to override with
  *
- * @param  {Object=}  instCallback  function to call in order to retrieve
- *                                  object to bind 'this' keyword to
- * @param  {number}   cid           class id
+ * @param  {Function}  instCallback  function to call in order to retrieve
+ *                                   object to bind 'this' keyword to
+ *
+ * @param  {number}   cid  class id
  *
  * @return  {function()}  override method
  */
diff --git a/lib/MethodWrapperFactory.js b/lib/MethodWrapperFactory.js
index bae8d8d..a83083f 100644
--- a/lib/MethodWrapperFactory.js
+++ b/lib/MethodWrapperFactory.js
@@ -25,19 +25,19 @@
 /**
  * Initializes factory to wrap methods
  *
- * @param  {function()}  getInst  function to determine instance and return
- *                                associated visibility object
+ * @param  {function(Function,Function,number)}  factory  function that will
+ *                                                        perform the actual
+ *                                                        wrapping
  *
- * @param  {function(function(),function(),number)}  factory  function that will
- *                                                            perform the actual
- *                                                            wrapping
+ * @constructor
  */
 module.exports = exports = function MethodWrapperFactory( factory )
 {
     // permit omission of the 'new' keyword for instantiation
     if ( !( this instanceof exports ) )
     {
-        return new exports( factory );
+        // module.exports for Closure Compiler
+        return new module.exports( factory );
     }
 
     this._factory = factory;
@@ -53,6 +53,8 @@ module.exports = exports = function MethodWrapperFactory( factory )
  * @param  {function()}  method        method to wrap
  * @param  {function()}  super_method  super method, if overriding
  * @param  {number}      cid           class id that method is associated with
+ * @param  {function()}  getInst       function to determine instance and return
+ *                                     associated visibility object
  */
 exports.prototype.wrapMethod = function( method, super_method, cid, getInst )
 {
diff --git a/lib/VisibilityObjectFactory.js b/lib/VisibilityObjectFactory.js
index 1be7f8a..5e48aae 100644
--- a/lib/VisibilityObjectFactory.js
+++ b/lib/VisibilityObjectFactory.js
@@ -33,13 +33,17 @@ var util = require( __dirname + '/util' );
  * The visibility object is the "magic" behind ease.js. This factory creates the
  * object that holds the varying levels of visibility, which are swapped out and
  * inherited depending on circumstance.
+ *
+ * @constructor
  */
 module.exports = exports = function VisibilityObjectFactory()
 {
     // permit omitting 'new' keyword
     if ( !( this instanceof exports ) )
     {
-        return new exports();
+        // module.exports instead of exports because Closure Compiler seems to
+        // be confused
+        return new module.exports();
     }
 };
 
@@ -105,6 +109,7 @@ exports.prototype.setup = function setup( dest, properties, methods )
  */
 exports.prototype._createPrivateLayer = function( atop_of, properties )
 {
+    /** @constructor */
     var obj_ctor = function() {};
     obj_ctor.prototype = atop_of;
 
@@ -126,7 +131,7 @@ exports.prototype._createPrivateLayer = function( atop_of, properties )
  *
  * @param  {Object}   dest            destination object
  * @param  {Object}   properties      properties to copy
- * @param  {Object=}  methods         methods to copy
+ * @param  {Object}   methods         methods to copy
  * @param  {boolean}  unless_keyword  do not set if keyword is set on existing
  *                                    method
  *
diff --git a/lib/VisibilityObjectFactoryFactory.js b/lib/VisibilityObjectFactoryFactory.js
index ddc9f0f..6ccf480 100644
--- a/lib/VisibilityObjectFactoryFactory.js
+++ b/lib/VisibilityObjectFactoryFactory.js
@@ -19,6 +19,10 @@
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  *
  * @author  Mike Gerwitz
+ * @package core
+ *
+ * XXX: Figure out how to resolve Closure Compiler's warning about shared type
+ * information
  */
 
 // XXX: Tightly coupled
diff --git a/lib/class.js b/lib/class.js
index a0832e8..473d09c 100644
--- a/lib/class.js
+++ b/lib/class.js
@@ -55,14 +55,14 @@ var util         = require( __dirname + '/util' ),
  * use the class's extend() method. If unavailable (or extending a non-ease.js
  * class/object), use the module's extend() method.
  *
- * @param  {string=}  name  optional name
- * @param  {Object}   def   class definition
+ * @param  {string|Object}  namedef  optional name or definition
+ * @param  {Object=}        def      class definition if first argument is name
  *
- * @return  {Class}  new class
+ * @return  {Function|Object}  new class or staging object
  */
-module.exports = function()
+module.exports = function( namedef, def )
 {
-    var type   = typeof arguments[ 0 ],
+    var type   = ( typeof namedef ),
         result = null
     ;
 
@@ -93,11 +93,12 @@ module.exports = function()
  * Creates a class, inheriting either from the provided base class or the
  * default base class
  *
- * @param  {Object}  base  object to extend (extends Class by default)
+ * @param  {Function|Object}  baseordfn   parent or definition object
+ * @param  {Object=}          dfn         definition object if parent provided
  *
- * @return  {Object}  extended class
+ * @return  {Function}  extended class
  */
-module.exports.extend = function( base )
+module.exports.extend = function( baseordfn, dfn )
 {
     return extend.apply( this, arguments );
 };
@@ -106,11 +107,11 @@ module.exports.extend = function( base )
 /**
  * Implements an interface or set of interfaces
  *
- * @param  {...Interface}  interfaces  interfaces to implement
+ * @param  {...Function}  interfaces  interfaces to implement
  *
- * @return  {Class}  new class containing interface abstractions
+ * @return  {Object}  intermediate interface object
  */
-module.exports.implement = function()
+module.exports.implement = function( interfaces )
 {
     // implement on empty base
     return createImplement(
@@ -188,7 +189,7 @@ module.exports.isA = module.exports.isInstanceOf;
  *
  * @param  {Object}  def  class definition
  *
- * @return  {Class}  new anonymous class
+ * @return  {Function}  new anonymous class
  */
 function createAnonymousClass( def )
 {
@@ -213,7 +214,8 @@ function createAnonymousClass( def )
  * @param  {string}  name  class name
  * @param  {Object}  def   class definition
  *
- * @return  {Class}  new named class
+ * @return  {Function|Object}  new named class or staging object if definition
+ *                             was not provided
  */
 function createNamedClass( name, def )
 {
@@ -368,9 +370,12 @@ function createImplement( base, ifaces, cname )
  * The class to inherit from (the first argument) is optional. If omitted, the
  * first argument will be considered to be the properties list.
  *
- * @return  {Object}  extended class
+ * @param  {Function|Object}  _   parent or definition object
+ * @param  {Object=}          __  definition object if parent was provided
+ *
+ * @return  {Function}  extended class
  */
-function extend()
+function extend( _, __ )
 {
     // set up the new class
     var new_class = class_builder.build.apply( class_builder, arguments );
@@ -392,12 +397,12 @@ function extend()
  * This will copy all of the abstract methods from the interface and merge it
  * into the given object.
  *
- * @param  {Object}        base        base object
- * @param  {...Interface}  interfaces  interfaces to implement into dest
+ * @param  {Object}       baseobj     base object
+ * @param  {...Function}  interfaces  interfaces to implement into dest
  *
  * @return  {Object}  destination object with interfaces implemented
  */
-var implement = function()
+var implement = function( baseobj, interfaces )
 {
     var args = Array.prototype.slice.call( arguments ),
         dest = {},
diff --git a/lib/class_abstract.js b/lib/class_abstract.js
index 7a7f9fc..5e04c6a 100644
--- a/lib/class_abstract.js
+++ b/lib/class_abstract.js
@@ -31,7 +31,7 @@ var Class = require( __dirname + '/class' );
 /**
  * Creates an abstract class
  *
- * @return  {Class}  abstract class
+ * @return  {Function}  abstract class
  */
 module.exports = exports = function()
 {
@@ -54,7 +54,7 @@ module.exports = exports = function()
 /**
  * Creates an abstract class from a class extend operation
  *
- * @return  {Class}  abstract class
+ * @return  {Function}  abstract class
  */
 exports.extend = function()
 {
@@ -85,7 +85,7 @@ exports.implement = function()
  * This function assumes the last argument to be the definition, which is the
  * common case, and modifies the object referenced by that argument.
  *
- * @param  {arguments}  args  arguments to parse
+ * @param  {Arguments}  args  arguments to parse
  *
  * @return  {undefined}
  */
diff --git a/lib/class_final.js b/lib/class_final.js
index 7b88ebf..ed32f20 100644
--- a/lib/class_final.js
+++ b/lib/class_final.js
@@ -27,7 +27,7 @@ var Class = require( __dirname + '/class' );
 /**
  * Creates a final class
  *
- * @return  {Class}  final class
+ * @return  {Function}  final class
  */
 exports = module.exports = function()
 {
@@ -48,7 +48,7 @@ exports = module.exports = function()
 /**
  * Creates a final class from a class extend operation
  *
- * @return  {Class}  final class
+ * @return  {Function}  final class
  */
 exports.extend = function()
 {
@@ -63,7 +63,7 @@ exports.extend = function()
  * This function assumes the last argument to be the definition, which is the
  * common case, and modifies the object referenced by that argument.
  *
- * @param  {arguments}  args  arguments to parse
+ * @param  {!Arguments}  args  arguments to parse
  *
  * @return  {undefined}
  */
diff --git a/lib/interface.js b/lib/interface.js
index 6c9149a..0f2b6ae 100644
--- a/lib/interface.js
+++ b/lib/interface.js
@@ -44,14 +44,14 @@ var util           = require( __dirname + '/util' ),
  * extended. To extend an existing interface, call its extend() method, or use
  * the extend() method of this module.
  *
- * @param  {string=}  name  optional name
- * @param  {Object}   def   interface definition
+ * @param  {string|Object}  namedef  optional name or definition
+ * @param  {Object=}        def      interface definition if first arg is name
  *
- * @return  {Interface}  new interface
+ * @return  {Function|Object}  new interface or staging object
  */
-module.exports = function()
+module.exports = function( namedef, def )
 {
-    var type   = typeof arguments[ 0 ],
+    var type   = ( typeof namedef ),
         result = null
     ;
 
@@ -82,7 +82,7 @@ module.exports = function()
 /**
  * Creates an interface
  *
- * @return  {Interface}  extended interface
+ * @return  {Function}  extended interface
  */
 module.exports.extend = function()
 {
@@ -123,7 +123,7 @@ function Interface() {}
  *
  * @param  {Object}  def  interface definition
  *
- * @return  {Interface}  new anonymous interface
+ * @return  {Function}  new anonymous interface
  */
 function createAnonymousInterface( def )
 {
@@ -148,7 +148,7 @@ function createAnonymousInterface( def )
  * @param  {string}  name  interface name
  * @param  {Object}  def   interface definition
  *
- * @return  {Interface}  new named interface
+ * @return  {Function}  new named interface
  */
 function createNamedInterface( name, def )
 {
diff --git a/lib/util.js b/lib/util.js
index 90b832f..04f5cd4 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -103,7 +103,7 @@ exports.definePropertyFallback = function( val )
  *
  * @param  {Object}  obj    object to set property on
  * @param  {string}  prop   name of property to set
- * @param  {mixed}   value  value to set
+ * @param  {*}       value  value to set
  *
  * @return  {undefined}
  */
@@ -113,10 +113,13 @@ exports.defineSecureProp = getDefineSecureProp();
 /**
  * Clones an object
  *
- * @param  {Object}   data  object to clone
- * @param  {boolean}  deep  perform deep clone (defaults to shallow)
+ * @param  {*}         data  object to clone
+ * @param  {boolean=}  deep  perform deep clone (defaults to shallow)
  *
- * @return  {Object}  cloned object
+ * @return  {*}  cloned object
+ *
+ * Closure Compiler ignores typeof checks and is thusly confused:
+ * @suppress {checkTypes}
  */
 exports.clone = function clone( data, deep )
 {
@@ -147,7 +150,7 @@ exports.clone = function clone( data, deep )
         // support toSource(), they'd still do the same damn thing.
         return data;
     }
-    else if ( data instanceof Object )
+    else if ( typeof data === 'object' )
     {
         var newobj = {},
             hasOwn = Object.prototype.hasOwnProperty;
@@ -247,8 +250,10 @@ exports.copyTo = function( dest, src, deep )
  * Parses object properties to determine how they should be interpreted in an
  * Object Oriented manner
  *
- * @param  {Object}  data     properties with names as the key
- * @param  {Object}  options  parser options and callbacks
+ * @param  {!Object}  data     properties with names as the key
+ *
+ * @param  {!{each,property,method,getset,keywordParser}}  options
+ *         parser options and callbacks
  *
  * @return undefined
  */
@@ -352,12 +357,12 @@ exports.propParse = function( data, options )
  * considered to be abstract and cannot be instantiated. It may only be
  * extended.
  *
- * @param  {...string}  definition  function definition that concrete
- *                                  implementations must follow
+ * @param  {...string}  def  function definition that concrete
+ *                           implementations must follow
  *
- * @return  {Function}
+ * @return  {function()}
  */
-exports.createAbstractMethod = function()
+exports.createAbstractMethod = function( def )
 {
     var definition = Array.prototype.slice.call( arguments );
 
@@ -377,9 +382,11 @@ exports.createAbstractMethod = function()
 /**
  * Determines if the given function is an abstract method
  *
- * @param  {Function}  function  function to inspect
+ * @param  {function()}  func  function to inspect
  *
  * @return  {boolean}  true if function is an abstract method, otherwise false
+ *
+ * @suppress {checkTypes}
  */
 exports.isAbstractMethod = function( func )
 {
@@ -424,21 +431,22 @@ exports.arrayShrink = function( items )
 /**
  * Uses Object.getOwnPropertyDescriptor if available, otherwise provides our own
  * implementation to fall back on
- *
- * If the environment does not support retrieving property descriptors (ES5),
- * then the following will be true:
- *  - get/set will always be undefined
- *  - writable, enumerable and configurable will always be true
- *  - value will be the value of the requested property on the given object
- *
- * @param  {Object}  obj   object to check property on
- * @param  {string}  prop  property to retrieve descriptor for
- *
- * @return  {Object}  descriptor for requested property or undefined if not found
  */
 exports.getOwnPropertyDescriptor =
-    ( can_define_prop && Object.getOwnPropertyDescriptor )
-    || function( obj, prop )
+    ( can_define_prop && Object.getOwnPropertyDescriptor ) ||
+    /**
+     * If the environment does not support retrieving property descriptors
+     * (ES5), then the following will be true:
+     *  - get/set will always be undefined
+     *  - writable, enumerable and configurable will always be true
+     *  - value will be the value of the requested property on the given object
+     *
+     * @param  {!Object}  obj   object to check property on
+     * @param  {string}   prop  property to retrieve descriptor for
+     *
+     * @return  {Object|undefined}  descriptor for requested property, if found
+     */
+    function( obj, prop )
     {
         if ( !Object.prototype.hasOwnProperty.call( obj, prop ) )
         {
@@ -481,9 +489,9 @@ exports.getPrototypeOf = Object.getPrototypeOf || function()
  * for example, not catch properties like Object.prototype.toString() when
  * searching for 'toString' on an object.
  *
- * @param  {Object}  obj     object to check property on
- * @param  {string}  prop    property to retrieve descriptor for
- * @param  {bool}    nobase  whether to ignore the base prototype
+ * @param  {Object}   obj     object to check property on
+ * @param  {string}   prop    property to retrieve descriptor for
+ * @param  {boolean}  nobase  whether to ignore the base prototype
  *
  * @return  {Object}  descriptor for requested property or undefined if not found
  */
diff --git a/lib/warn.js b/lib/warn.js
index 4f31825..1826019 100644
--- a/lib/warn.js
+++ b/lib/warn.js
@@ -23,7 +23,7 @@
 
 /**
  * Active warning handler
- * @type {function()}
+ * @type {?function( Warning )}
  */
 var _handler = null;
 
@@ -47,6 +47,8 @@ var _console = ( typeof console !== 'undefined' ) ? console : undefined;
  * @param {Error} e exception (error) to wrap
  *
  * @return {Warning} new warning instance
+ *
+ * @constructor
  */
 var Warning = exports.Warning = function( e )
 {
diff --git a/tools/combine.tpl b/tools/combine.tpl
index 67496f8..12d2304 100644
--- a/tools/combine.tpl
+++ b/tools/combine.tpl
@@ -36,7 +36,9 @@ var easejs = {};
      *
      * @param  {string}  module_id  id of the module to load
      *
-     * @return  {Object}  exports of requested module
+     * return tag intentionally omitted; too many potential return types and
+     * setting return type of {*} will throw warnings for those attempting to
+     * treat the return value as a function
      */
     var require = function( module_id )
     {
diff --git a/tools/externs.js b/tools/externs.js
new file mode 100644
index 0000000..383937f
--- /dev/null
+++ b/tools/externs.js
@@ -0,0 +1,4 @@
+/**
+ * Externs for ease.js
+ */
+
diff --git a/tools/mkexterns b/tools/mkexterns
index c8b841c..f2e83b5 100755
--- a/tools/mkexterns
+++ b/tools/mkexterns
@@ -4,9 +4,6 @@
 # have restricted scope. This means that they cannot be used as types in other
 # modules. Therefore, to permit this, we must generate an extern file containing
 # basic definitions of each.
-#
-# This is used only for compilation and is otherwise completely unnecessary. As
-# such, to reduce maintenance overhead, the creation of this file is automated.
 # #
 
 # all CamelCase modules are likely to be ctors
@@ -21,3 +18,14 @@ for module in $modules; do
     echo "function $module() {};"
     echo
 done
+
+# finally, there's some additional useful metadata that we use to make our lives
+# easier, better documented and more consistent
+cat <<ETC
+
+/** @typedef {{abstractMethods: Object}} */
+var __class_meta;
+
+/** @typedef {{public: Object, protected: Object, private: Object}} */
+var __visobj;
+ETC