* minor refactorings

 * added missing JsDoc headers

lib/ringo/storage/sql/basedialect.js

@@ -2,22 +2,55 @@ var types = require("./types");
 
 export("BaseDialect");
 
+/**
+ * Creates a new base dialect
+ * @class Instances of this class represent a base database dialect, containing
+ * mappings from JDBC types to column data types
+ * @returns A newly created BaseDialect instance
+ * @constructor
+ */
 function BaseDialect() {
     var jdbcTypeMap = {};
     var columnTypes = {};
 
+    /**
+     * Contains the opening quote character used to quote table and column names
+     * @type String
+     */
     Object.defineProperty(this, "openQuote", {"value": '"'});
+
+    /**
+     * Contains the closing quote character used to quote table and column names
+     * @type String
+     */
     Object.defineProperty(this, "closeQuote", {"value": '"'});
 
+    /**
+     * Registers a column data type for the given JDBC type number
+     * @param {Number} jdbcTypeNumber The JDBC type number
+     * @param {Object} dataType The data type to register
+     */
     this.registerJdbcType = function(jdbcTypeNumber, dataType) {
         jdbcTypeMap[jdbcTypeNumber] = dataType;
+        return;
     };
 
+    /**
+     * Registers a column type for the given internal type name
+     * @param {String} typeName The internal type name
+     * @param {ColumnType} columnType The column type to register
+     */
     this.registerColumnType = function(typeName, columnType) {
         columnTypes[typeName] = columnType;
         return;
     };
 
+    /**
+     * Returns the column type for the given internal type name
+     * @param {String} name The internal type name
+     * @returns The column type
+     * @type ColumnType
+     */
     this.getColumnType = function(name) {
         var columnType = columnTypes[name];
         if (columnType == null) {
@@ -26,6 +59,11 @@ function BaseDialect() {
         return columnType;
     };
 
+    /**
+     * Returns the data type for the given JDBC type number
+     * @param {Number} number The JDBC type number
+     * @returns The data type
+     */
     this.getJdbcType = function(number) {
         var jdbcType = jdbcTypeMap[number];
         if (jdbcType == null) {
@@ -44,6 +82,7 @@ function BaseDialect() {
         return this.getJdbcType(columnType.jdbcType);
     };
 
+    // register data types for JDBC types
     this.registerJdbcType(java.sql.Types.BIGINT, new types.IntegerType());
     this.registerJdbcType(java.sql.Types.BINARY, new types.BinaryType());
     this.registerJdbcType(java.sql.Types.BIT, new types.BooleanType());
@@ -151,6 +190,12 @@ BaseDialect.prototype.getSqlRange = function(sql, offset, limit) {
     throw new Error("Range not implemented");
 };
 
+/**
+ * Returns the name of the default schema. Dialect implementations can override this.
+ * @param {java.sql.Connection} conn The connection to use
+ * @returns The name of the default schema
+ * @type String
+ */
 BaseDialect.prototype.getDefaultSchema = function(conn) {
     return null;
 };

lib/ringo/storage/sql/collection.js

@@ -1,27 +1,63 @@
 export("Collection");
 
+/**
+ * Creates a new Collection instance
+ * @class Instances of this class represent a collection object, mimicking
+ * a JS array. Note that it's currently not possible to directly access objects
+ * using index positions (eg. collection[0]), use get(index) instead. Iterating
+ * using for, for each or forEach is supported
+ * @param {String} name The property name of the collection
+ * @param {Query} query The query used to populate the collection
+ * @returns A newly created Collection instance
+ * @constructor
+ */
 var Collection = function(name, query) {
     var isInitialized = false;
     var objects = [];
 
+    /**
+     * Initializes the collection
+     */
+    var initialize = function() {
+        if (!isInitialized) {
+            objects = query.select();
+        }
+        isInitialized = true;
+        return;
+    };
+
+    /**
+     * Contains the property name of the collection
+     * @type String
+     */
     Object.defineProperty(this, "name", {"value": name});
 
+    /**
+     * Contains the length of the collection
+     * @type Number
+     */
     Object.defineProperty(this, "length", {
         "get": function() {
             initialize();
             return objects.length;
         }
     });
 
-
-    var initialize = function() {
-        if (!isInitialized) {
-            objects = query.select();
-        }
-        isInitialized = true;
-        return;
+    /**
+     * Returns a collection iterator instance
+     * @returns A collection iterator
+     * @type CollectionIterator
+     */
+    this.__iterator__ = function() {
+        initialize();
+        return new CollectionIterator(this);
     };
 
+    /**
+     * Returns the object at the given index position
+     * @param {Number} idx The index position
+     * @returns The object at the given index position
+     */
     this.get = function(idx) {
         initialize();
         if (idx >= 0 && idx < objects.length) {
@@ -30,12 +66,12 @@ var Collection = function(name, query) {
         return null;
     };
 
-    this.__iterator__ = function() {
-        initialize();
-        return new CollectionIterator(this);
-    };
-
-    this.forEach = function() {
+    /**
+     * Iterates over this collection
+     * @param {Function} func The callback function to execute for each
+     * object in this collection
+     */
+    this.forEach = function(func) {
         return Array.prototype.forEach.apply(objects, arguments);
     };
 
@@ -50,10 +86,21 @@ Collection.prototype.toString = function() {
 };
 
 
-
+/**
+ * Creates a new collection iterator
+ * @class A collection iterator
+ * @param {Collection} collection The collection to operate on
+ * @returns A newly created collection iterator
+ * @constructor
+ */
 var CollectionIterator = function(collection) {
     var idx = 0;
 
+    /**
+     * Returns the next element in the collection, or throws a StopIteration
+     * if the end of the collection is reached
+     * @returns The next element in the collection
+     */
     this.next = function() {
         if (idx < collection.length) {
             return collection.get(idx++);

lib/ringo/storage/sql/connectionpool.js

@@ -2,10 +2,23 @@ var log = require('ringo/logging').getLogger(module.id);
 
 export("ConnectionPool");
 
+/**
+ * Creates a new connection pool instance
+ * @class Instances of this class represent a connection pool
+ * @param {Object} props The connection properties to use
+ * @param {Number} maxConnections Optional maximum connections (defaults to 10)
+ * @returns A newly created connection pool
+ * @constructor
+ */
 var ConnectionPool = function(props, maxConnections) {
 
     var connections = [];
-
+
+    /**
+     * Searches for an unused connection and returns it.
+     * @returns An unused connect
+     * @type Connection
+     */
     this.getConnection = function() {
         var conn = null;
         for each (var conn in connections) {
@@ -37,9 +50,12 @@ ConnectionPool.prototype.toString = function() {
 };
 
 /**
- * @param pool
- * @param conn
- * @returns
+ * Creates a new Connection wrapper instance
+ * @class Instances of this class wrap a JDBC connection. Note that calling
+ * close() doesn't actually close the connection but marks it as unused.
+ * @param {ConnectionPool} pool The connection pool this connection belongs to
+ * @param {java.sql.Connection} conn The connection to wrap
+ * @returns A newly created Connection instance
  * @constructor
  */
 var Connection = function(pool, conn) {
@@ -122,13 +138,13 @@ Connection.prototype = (function() {
 })();
 
 /**
- * Returns true if this connection is still valid
+ * Returns true if this connection is still valid. This method connects to the
+ * database if it wasn't used for one minute.
  * @returns True if this connection is still valid
  * @type Boolean
  */
 Connection.prototype.isValid = function() {
-    var now = new Date();
-    return (now.getTime() - this.getLastUse() < 60000) || this.validate();
+    return (new Date().getTime() - this.getLastUse() < 60000) || this.validate();
 };
 
 /**