From 98690a4881a9cafa957c7d9afa96b9a62f1ed97d Mon Sep 17 00:00:00 2001
From: Raymond Feng <raymond@strongloop.com>
Date: Thu, 23 May 2013 22:40:33 -0700
Subject: [PATCH] Add docs

---
 lib/sql.js | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/lib/sql.js b/lib/sql.js
index 440404b0..20b543f0 100644
--- a/lib/sql.js
+++ b/lib/sql.js
@@ -21,6 +21,11 @@ BaseSQL.prototype.queryOne = function (sql, callback) {
     });
 };
 
+/**
+ * Look up the data source by model name
+ * @param model The model name
+ * @returns {DataSource} The data source
+ */
 BaseSQL.prototype.dataSource = function(model) {
     var m = this._models[model];
     if(!m) {
@@ -29,6 +34,11 @@ BaseSQL.prototype.dataSource = function(model) {
     return m.model.schema;
 }
 
+/**
+ * Get the table name for a given model
+ * @param model The model name
+ * @returns {String} The table name
+ */
 BaseSQL.prototype.table = function (model) {
     var name = this.dataSource(model).tableName(model);
     var dbName = this.dbName;
@@ -38,6 +48,12 @@ BaseSQL.prototype.table = function (model) {
     return name;
 };
 
+/**
+ * Get the column name for given model property
+ * @param model The model name
+ * @param property The property name
+ * @returns {String} The column name
+ */
 BaseSQL.prototype.column = function (model, property) {
     var name = this.dataSource(model).columnName(model, property);
     var dbName = this.dbName;
@@ -47,6 +63,12 @@ BaseSQL.prototype.column = function (model, property) {
     return name;
 };
 
+/**
+ * Get the corresponding property name for a given column name
+ * @param model The model name
+ * @param column The column name
+ * @returns {*}
+ */
 BaseSQL.prototype.propertyName = function (model, column) {
     var props = this._models[model].properties;
     for(var p in props) {
@@ -57,10 +79,20 @@ BaseSQL.prototype.propertyName = function (model, column) {
     return null;
 };
 
+/**
+ * Get the id property name
+ * @param model The model name
+ * @returns {String} The id property name
+ */
 BaseSQL.prototype.idName = function (model) {
     return this.dataSource(model).idName(model);
 };
 
+/**
+ * Get the id column name
+ * @param model The model name
+ * @returns {String} The column name
+ */
 BaseSQL.prototype.idColumn = function (model) {
     var name = this.dataSource(model).idColumnName(model);;
     var dbName = this.dbName;
@@ -70,10 +102,21 @@ BaseSQL.prototype.idColumn = function (model) {
     return name;
 };
 
+/**
+ * Get the escaped id column name
+ * @param model The model name
+ * @returns {String} the escaped id column name
+ */
 BaseSQL.prototype.idColumnEscaped = function (model) {
     return this.escapeName(this.dataSource(model).idColumnName(model));
 };
 
+/**
+ * Get the id index (sequence number, starting from 1)
+ * @param model The model name
+ * @param prop The property name
+ * @returns {Number} The id index, undefined if the property is not part of the primary key
+ */
 BaseSQL.prototype.id = function (model, prop) {
     var p = this._models[model].properties[prop];
     if(!p) {
@@ -82,14 +125,29 @@ BaseSQL.prototype.id = function (model, prop) {
     return p.id;
 };
 
+/**
+ * Escape the name for the underlying database
+ * @param name The name
+ */
 BaseSQL.prototype.escapeName = function (name) {
     throw new Error('escapeName method should be declared in adapter');
 };
 
+/**
+ * Get the escaped table name
+ * @param model The model name
+ * @returns {String} the escaped table name
+ */
 BaseSQL.prototype.tableEscaped = function (model) {
     return this.escapeName(this.table(model));
 };
 
+/**
+ * Get the escaped column name for a given model property
+ * @param model The model name
+ * @param property The property name
+ * @returns {String} The escaped column name
+ */
 BaseSQL.prototype.columnEscaped = function (model, property) {
     return this.escapeName(this.column(model, property));
 };