From 5a6155e08efc29425dfc0ecf1e88197a00fc27c5 Mon Sep 17 00:00:00 2001
From: Raymond Feng <raymond@strongloop.com>
Date: Fri, 17 Jan 2014 10:40:41 -0800
Subject: [PATCH] Clean up loopback.js doc and add it to docs.json

---
 docs.json       |  2 ++
 lib/loopback.js | 25 +++++++++++++++++++------
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/docs.json b/docs.json
index 348ba7f7..2803f2db 100644
--- a/docs.json
+++ b/docs.json
@@ -2,6 +2,8 @@
   "title": "LoopBack Documentation",
   "content": [
     "lib/application.js",
+    {"title": "LoopBack", "depth": 3},
+    "lib/loopback.js",
     {"title": "Middleware", "depth": 3},
     "lib/middleware/token.js",
     "lib/models/access-token.js",
diff --git a/lib/loopback.js b/lib/loopback.js
index 18c3795b..d5db06df 100644
--- a/lib/loopback.js
+++ b/lib/loopback.js
@@ -1,4 +1,4 @@
-/**
+/*!
  * Module dependencies.
  */
 
@@ -15,7 +15,15 @@ var express = require('express')
   , i8n = require('inflection');
 
 /**
- * Expose `createApplication()`.
+ * `loopback` is the main entry for LoopBack core module. It provides static
+ * methods to create models and data sources. The module itself is a function
+ * that creates loopback `app`. For example,
+ *
+ *
+ * ```js
+ * var loopback = require('loopback');
+ * var app = loopback();
+ * ```
  */
 
 var loopback = exports = module.exports = createApplication;
@@ -47,7 +55,7 @@ function createApplication() {
   return app;
 }
 
-/**
+/*!
  * Expose express.middleware as loopback.*
  * for example `loopback.errorHandler` etc.
  */
@@ -59,7 +67,7 @@ for (var key in express) {
     , Object.getOwnPropertyDescriptor(express, key));
 }
 
-/**
+/*!
  * Expose additional loopback middleware
  * for example `loopback.configure` etc.
  */
@@ -73,7 +81,7 @@ fs
     loopback[m.replace(/\.js$/, '')] = require('./middleware/' + m);
   });
 
-/**
+/*!
  * Error handler title
  */
 
@@ -197,6 +205,9 @@ loopback.getModel = function(modelName) {
 
 /**
  * Set the default `dataSource` for a given `type`.
+ * @param {String} type The datasource type
+ * @param {Object|DataSource} dataSource The data source settings or instance
+ * @return {DataSource} The data source instance
  */
 
 loopback.setDefaultDataSourceForType = function(type, dataSource) {
@@ -212,6 +223,8 @@ loopback.setDefaultDataSourceForType = function(type, dataSource) {
 
 /**
  * Get the default `dataSource` for a given `type`.
+ * @param {String} type The datasource type
+ * @return {DataSource} The data source instance
  */
 
 loopback.getDefaultDataSourceForType = function(type) {
@@ -262,7 +275,7 @@ loopback.RoleMapping = require('./models/role').RoleMapping;
 loopback.ACL = require('./models/acl').ACL;
 loopback.Scope = require('./models/acl').Scope;
 
-/**
+/*!
  * Automatically attach these models to dataSources
  */