JS stdlib: added some JSDoc annotations to handwritten js files.

js/js.translator/testData/kotlin_lib.js

@@ -14,22 +14,24 @@
  * limitations under the License.
  */
 
-"use strict";
-
-// todo inlined
-String.prototype.startsWith = function (s) {
-    return this.indexOf(s) === 0;
-};
-
-String.prototype.endsWith = function (s) {
-    return this.indexOf(s, this.length - s.length) !== -1;
-};
-
-String.prototype.contains = function (s) {
-    return this.indexOf(s) !== -1;
-};
-
 (function () {
+    "use strict";
+
+    // Shims for String
+    String.prototype.startsWith = function (s) {
+        return this.indexOf(s) === 0;
+    };
+
+    String.prototype.endsWith = function (s) {
+        return this.indexOf(s, this.length - s.length) !== -1;
+    };
+
+    String.prototype.contains = function (s) {
+        return this.indexOf(s) !== -1;
+    };
+
+    // Kotlin stdlib
+
     Kotlin.equals = function (obj1, obj2) {
         if (obj1 == null) {
             return obj2 == null;
@@ -95,16 +97,31 @@ String.prototype.contains = function (s) {
         };
     }
 
+    /**
+     * @interface
+     * @template T
+     */
     Kotlin.Iterator = Kotlin.createClassNow(null, null, {
         next: throwAbstractFunctionInvocationError("Iterator#next"),
         hasNext: throwAbstractFunctionInvocationError("Iterator#hasNext")
     });
 
+    /**
+     * @class
+     * @implements {Kotlin.Iterator.<T>}
+     *
+     * @constructor
+     * @param {Array.<T>} array
+     * @template T
+     */
     var ArrayIterator = Kotlin.createClassNow(Kotlin.Iterator,
+        /** @constructs */
         function (array) {
             this.array = array;
             this.index = 0;
-        }, {
+        },
+        /** @lends {ArrayIterator.prototype} */
+        {
             next: function () {
                 return this.array[this.index++];
             },
@@ -118,7 +135,16 @@ String.prototype.contains = function (s) {
             }
     });
 
+    /**
+     * @class
+     * @extends {ArrayIterator.<T>}
+     *
+     * @constructor
+     * @param {Kotlin.AbstractList.<T>} list
+     * @template T
+     */
     var ListIterator = Kotlin.createClassNow(ArrayIterator,
+        /** @constructs */
         function (list) {
             this.list = list;
             this.size = list.size();
@@ -129,6 +155,10 @@ String.prototype.contains = function (s) {
             }
     });
 
+    /**
+     * @interface
+     * @template T
+     */
     Kotlin.Collection = Kotlin.createClassNow();
 
     Kotlin.Enum = Kotlin.createClassNow(null,
@@ -262,6 +292,10 @@ String.prototype.contains = function (s) {
         }
     });
 
+    /**
+     * @interface // actually it's abstract class
+     * @template T
+     */
     Kotlin.AbstractList = Kotlin.createClassNow(Kotlin.AbstractCollection, null, {
         iterator: function () {
             return new ListIterator(this);
@@ -476,16 +510,33 @@ String.prototype.contains = function (s) {
         }
     });
 
+    /**
+     * @interface
+     * @template T
+     */
     Kotlin.Comparator = Kotlin.createClassNow(null, null, {
         compare: throwAbstractFunctionInvocationError("Comparator#compare")
     });
 
+    /**
+     * @class
+     * @implements {Kotlin.Comparator.<T>}
+     *
+     * @constructor
+     * @param {function(T,T): Boolean} comparator
+     * @template T
+     */
     var ComparatorImpl = Kotlin.createClassNow(Kotlin.Comparator,
         function (comparator) {
             this.compare = comparator;
         }
     );
 
+    /**
+     * @param {function(T,T): Boolean} f
+     * @returns {Kotlin.Comparator.<T>}
+     * @template T
+     */
     Kotlin.comparator = function (f) {
         return new ComparatorImpl(f);
     };

js/js.translator/testData/kotlin_lib_ecma5.js

@@ -124,12 +124,24 @@ var Kotlin = {};
         return metadata;
     }
 
+    /**
+     * @this {{object_initializer$: (function(): Object)}}
+     * @returns {Object}
+     */
     function class_object() {
         var object = this.object_initializer$();
         Object.defineProperty(this, "object", {value: object});
         return object;
     }
 
+    /**
+     * @param {(Array|Object|null)=} bases
+     * @param {(function(new: T, ?, ?, ?, ?, ?, ?, ?): T)|null=} constructor
+     * @param {Object=} properties
+     * @param {Object=} staticProperties
+     * @returns {function(new: T): T}
+     * @template T
+     */
     Kotlin.createClassNow = function (bases, constructor, properties, staticProperties) {
         if (constructor == null) {
             constructor = emptyFunction();
@@ -192,6 +204,13 @@ var Kotlin = {};
         }
     }
 
+    /**
+     * @param {(function():Array.<*>)|null} basesFun
+     * @param {?=} constructor
+     * @param {Object=} properties
+     * @param {Object=} staticProperties
+     * @returns {*}
+     */
     Kotlin.createClass = function (basesFun, constructor, properties, staticProperties) {
         function $o() {
             var klass = Kotlin.createClassNow(getBases(basesFun), constructor, properties, staticProperties);
@@ -203,6 +222,12 @@ var Kotlin = {};
         return $o;
     };
 
+    /**
+     * @param {(function():Array.<*>)|null} basesFun
+     * @param {Object=} properties
+     * @param {Object=} staticProperties
+     * @returns {*}
+     */
     Kotlin.createTrait = function (basesFun, properties, staticProperties) {
         function $o() {
             var klass = Kotlin.createTraitNow(getBases(basesFun), properties, staticProperties);
@@ -214,6 +239,13 @@ var Kotlin = {};
         return $o;
     };
 
+    /**
+     * @param {function()|null} basesFun
+     * @param {(function(new: T): T)|null=} constructor
+     * @param {Object=} functions
+     * @returns {Object}
+     * @template T
+     */
     Kotlin.createObject = function (basesFun, constructor, functions) {
         return Kotlin.createObjectNow(getBases(basesFun), constructor, functions);
     };
@@ -306,6 +338,11 @@ var Kotlin = {};
         return definition;
     }
 
+    /**
+     * @param {function()|null=} initializer
+     * @param {Object=} members
+     * @returns {Object}
+     */
     Kotlin.definePackage = function (initializer, members) {
         var definition = createDefinition(members);
         if (initializer === null) {
@@ -329,6 +366,10 @@ var Kotlin = {};
         return definition;
     };
 
+    /**
+     * @param {string} id
+     * @param {Object} declaration
+     */
     Kotlin.defineModule = function (id, declaration) {
         if (id in Kotlin.modules) {
             throw new Error("Module " + id + " is already defined");

js/js.translator/testData/maps.js

@@ -14,8 +14,10 @@
  * limitations under the License.
  */
 
-"use strict";
 (function () {
+    "use strict";
+
+    /** @const */
     var FUNCTION = "function";
     var arrayRemoveAt = (typeof Array.prototype.splice == FUNCTION) ?
                         function (arr, idx) {
@@ -83,6 +85,14 @@
 
     var checkKey = createKeyValCheck("key"), checkValue = createKeyValCheck("value");
 
+    /**
+     * @constructor
+     * @param {string} hash
+     * @param {Key} firstKey
+     * @param {Value} firstValue
+     * @param {(function(Key, Key): boolean)|null|undefined} equalityFunction
+     * @template  Key, Value
+     */
     function Bucket(hash, firstKey, firstValue, equalityFunction) {
         this[0] = hash;
         this.entries = [];
@@ -197,6 +207,14 @@
 
     /*----------------------------------------------------------------------------------------------------------------*/
 
+    /**
+     * @class
+     *
+     * @constructor
+     * @param {(function(Key): string)=} hashingFunctionParam
+     * @param {(function(Key, Key): boolean)=} equalityFunctionParam
+     * @template Key, Value
+     */
     var Hashtable = function (hashingFunctionParam, equalityFunctionParam) {
         var that = this;
         var buckets = [];
@@ -346,7 +364,10 @@
             }
         };
 
-
+        /**
+         * @param {Hashtable.<Key, Value>} hashtable
+         * @param {(function(Key, Value, Value): Value)=} conflictCallback
+         */
         this.putAll_za3j1t$ = function (hashtable, conflictCallback) {
             var entries = hashtable._entries();
             var entry, key, value, thisValue, i = entries.length;
@@ -381,10 +402,13 @@
         };
     };
 
-
     Kotlin.HashTable = Hashtable;
 })();
 
+/**
+ * @interface
+ * @template Key, Value
+ */
 Kotlin.Map = Kotlin.createClassNow();
 
 Kotlin.HashMap = Kotlin.createClassNow(Kotlin.Map,
@@ -396,6 +420,15 @@ Kotlin.HashMap = Kotlin.createClassNow(Kotlin.Map,
 Kotlin.ComplexHashMap = Kotlin.HashMap;
 
 (function () {
+    /**
+     * @class
+     * @implements Kotlin.Iterator.<Value>
+     *
+     * @constructor
+     * @param {Kotlin.Map.<Key, Value>} map
+     * @param {Array.<Value>} keys
+     * @template Key, Value
+     */
     var PrimitiveHashMapValuesIterator = Kotlin.createClassNow(Kotlin.Iterator,
         function (map, keys) {
             this.map = map;
@@ -411,6 +444,14 @@ Kotlin.ComplexHashMap = Kotlin.HashMap;
             }
     });
 
+    /**
+     * @class
+     * @implements Kotlin.Collection.<Value>
+     *
+     * @constructor
+     * @param {Kotlin.PrimitiveHashMap.<Key, Value>} map
+     * @template Key, Value
+     */
     var PrimitiveHashMapValues = Kotlin.createClassNow(Kotlin.Collection,
         function (map) {
             this.map = map;
@@ -421,11 +462,18 @@ Kotlin.ComplexHashMap = Kotlin.HashMap;
             isEmpty: function () {
                 return this.map.$size === 0;
             },
+            // TODO: test it
             contains: function (o) {
                 return this.map.containsValue_za3rmp$(o);
             }
     });
 
+    /**
+     * @class
+     * @implements Kotlin.Map.<Key, Value>
+     * @constructor
+     * @template Key, Value
+     */
     Kotlin.PrimitiveHashMap = Kotlin.createClassNow(Kotlin.Map,
         function () {
             this.$size = 0;
@@ -502,14 +550,24 @@ Kotlin.ComplexHashMap = Kotlin.HashMap;
     });
 }());
 
+/**
+ * @interface
+ */
 Kotlin.Set = Kotlin.createClassNow(Kotlin.Collection);
 
+/**
+ * @class
+ * @constructor
+ * @param {Kotlin.Set} set
+ */
 var SetIterator = Kotlin.createClassNow(Kotlin.Iterator,
     function (set) {
         this.set = set;
         this.keys = set.toArray();
         this.index = 0;
-    }, {
+    },
+    /** @lends SetIterator.prototype */
+    {
         next: function () {
             return this.keys[this.index++];
         },
@@ -521,12 +579,21 @@ var SetIterator = Kotlin.createClassNow(Kotlin.Iterator,
         }
 });
 
+/**
+ * @class
+ * @constructor
+ * @extends {Kotlin.Collection.<T>}
+ * @template T
+ */
 Kotlin.PrimitiveHashSet = Kotlin.createClassNow(Kotlin.AbstractCollection,
+    /** @constructs */
     function () {
         this.$size = 0;
         this.map = {};
-    }, {
+    },
-        contains_za3rmp$: function (key) {
+    /** @lends {Kotlin.PrimitiveHashSet.prototype} */
+    {
+        contains_s9cetl$: function (key) {
             return this.map[key] === true;
         },
         iterator: function () {
@@ -563,6 +630,13 @@ Kotlin.PrimitiveHashSet = Kotlin.createClassNow(Kotlin.AbstractCollection,
 });
 
 (function () {
+    /**
+     * @class
+     * @constructor
+     * @param {(function(Key): string)=} hashingFunction
+     * @param {(function(Key, Key): boolean)=} equalityFunction
+     * @template Key, Value
+     */
     function HashSet(hashingFunction, equalityFunction) {
         var hashTable = new Kotlin.HashTable(hashingFunction, equalityFunction);
 
@@ -579,6 +653,7 @@ Kotlin.PrimitiveHashSet = Kotlin.createClassNow(Kotlin.AbstractCollection,
             return hashTable._keys();
         };
 
+        /** @suppress {checkTypes} */
         this.iterator = function () {
             return new SetIterator(this);
         };