From be9a144f477e865080a89a8a8918db1548816965 Mon Sep 17 00:00:00 2001
From: Anatoliy Chakkaev <rpm1602@gmail.com>
Date: Sun, 24 Mar 2013 04:43:47 +0400
Subject: [PATCH] Added docs

---
 docs/adapter.md      |   2 +
 docs/hooks.md        |   2 +
 docs/html/index.html |  50 +++++++++++++----
 docs/index.txt       |  15 ++++++
 docs/jugglingdb.md   |  28 ++++++++--
 docs/model.md        |  15 ++++++
 docs/schema.md       | 126 +++++++++++++++++++++++++++++++++++++++++++
 docs/validations.md  |   2 +
 scripts/doc.sh       |   2 +-
 9 files changed, 228 insertions(+), 14 deletions(-)
 create mode 100644 docs/adapter.md
 create mode 100644 docs/hooks.md
 create mode 100644 docs/model.md
 create mode 100644 docs/schema.md
 create mode 100644 docs/validations.md

diff --git a/docs/adapter.md b/docs/adapter.md
new file mode 100644
index 00000000..c2fdd6cd
--- /dev/null
+++ b/docs/adapter.md
@@ -0,0 +1,2 @@
+jugglingdb-adapter(3) - Adapter API explained.
+====================
diff --git a/docs/hooks.md b/docs/hooks.md
new file mode 100644
index 00000000..0026eb8e
--- /dev/null
+++ b/docs/hooks.md
@@ -0,0 +1,2 @@
+jugglingdb-hooks(3) - Hooks and object lifecycle.
+==================
diff --git a/docs/html/index.html b/docs/html/index.html
index be1ed638..981f993a 100644
--- a/docs/html/index.html
+++ b/docs/html/index.html
@@ -41,6 +41,12 @@
   ol.man-decor li.tc {text-align:center;letter-spacing:4px}
   ol.man-decor li.tr {text-align:right;float:right}
   </style>
+  <style type='text/css' media='print'>
+  /* style: print */
+  .mp {max-width:none}
+  .man-navigation {display:none !important}
+  .mp a[href]:not([href^="#"]):not([data-bare-link]):after {content:" " attr(href)}
+  </style>
   <style type='text/css' media='all'>
   /* style: toc */
   .man-navigation {display:block !important;position:fixed;top:0;left:113ex;height:100%;width:100%;padding:48px 0 0 0;border-left:1px solid #dbdbdb;background:#eee}
@@ -68,7 +74,7 @@
     <a href="#FUTURE">FUTURE</a>
     <a href="#BUGS">BUGS</a>
     <a href="#HISTORY">HISTORY</a>
-    <a href="#LICENSE">LICENSE</a>
+    <a href="#COPYRIGHT">COPYRIGHT</a>
     <a href="#AUTHOR">AUTHOR</a>
     <a href="#CONTRIBUTORS">CONTRIBUTORS</a>
     <a href="#SEE-ALSO">SEE ALSO</a>
@@ -115,7 +121,8 @@ which allows to write rich client-side apps talking to server using JSON API.</p
 
 <h2 id="DOCUMENTATION">DOCUMENTATION</h2>
 
-<p>Autogenerated documentation available at <a href="https://jsdoc.info/1602/jugglingdb">jsdoc.info/1602/jugglingdb</a>. Human-written manual sections are:</p>
+<p>Autogenerated documentation available at <a href="http://jsdoc.info/1602/jugglingdb">jsdoc.info/1602/jugglingdb</a>.
+Human-written manual sections are:</p>
 
 <dl>
 <dt><a class="man-ref" href="schema.3.html">jugglingdb-schema<span class="s">(3)</span></a></dt><dd><p>Everything about schema, data types and model definition.</p></dd>
@@ -123,16 +130,33 @@ which allows to write rich client-side apps talking to server using JSON API.</p
 <dt><a class="man-ref" href="validations.3.html">jugglingdb-validations<span class="s">(3)</span></a></dt><dd><p>Built-in validators, creating custom validations, syncronous and asyncronous
 object validation.</p></dd>
 <dt><a class="man-ref" href="hooks.3.html">jugglingdb-hooks<span class="s">(3)</span></a></dt><dd><p>Hooks and object lifecycle.</p></dd>
+<dt><span class="man-ref">jugglingdb-adapter<span class="s">(3)</span></span></dt><dd><p>Adapter API explained.</p></dd>
 </dl>
 
 
 <h2 id="ADAPTERS">ADAPTERS</h2>
 
+<p>All adapters available as separate packages at
+<a href="https://github.com/jugglingdb">github.com/jugglingdb</a> and published in npm.</p>
+
+<ul>
+<li><a href="https://github.com/jugglingdb/mysql-adapter">jugglingdb-mysql</a></li>
+<li><a href="https://github.com/jugglingdb/sqlite3-adapter">jugglingdb-sqlite3</a></li>
+<li><a href="https://github.com/jugglingdb/postgres-adapter">jugglingdb-postgres</a></li>
+<li><a href="https://github.com/jugglingdb/redis-adapter">jugglingdb-redis</a></li>
+<li><a href="https://github.com/jugglingdb/mongodb-adapter">jugglingdb-mongodb</a></li>
+<li><a href="https://github.com/jugglingdb/nano-adapter">jugglingdb-nano</a></li>
+<li><a href="https://github.com/jugglingdb/firebird-adapter">jugglingdb-firebird</a></li>
+</ul>
+
+
 <h2 id="CONTRIBUTION">CONTRIBUTION</h2>
 
+<p>TODO: briefly describe contribution</p>
+
 <h2 id="FUTURE">FUTURE</h2>
 
-<p>See <a class="man-ref" href="roadmap.3.html">jugglingdb-roadmap<span class="s">(3)</span></a> and [github issues][issues] to catch up current
+<p>See <a class="man-ref" href="roadmap.3.html">jugglingdb-roadmap<span class="s">(3)</span></a> and <a href="https://github.com/1602/jugglingdb/issues?state=open">github issues</a> to catch up current
 development and see how you can help jugglingdb to grow up.</p>
 
 <h2 id="BUGS">BUGS</h2>
@@ -142,17 +166,20 @@ development and see how you can help jugglingdb to grow up.</p>
 <dl>
 <dt>github/core</dt><dd><a href="https://github.com/1602/jugglingdb/issues" data-bare-link="true">https://github.com/1602/jugglingdb/issues</a></dd>
 <dt>github/adapters</dt><dd><a href="https://github.com/jugglingdb" data-bare-link="true">https://github.com/jugglingdb</a></dd>
-<dt class="flush">email</dt><dd><a href="&#109;&#97;&#105;&#108;&#116;&#x6f;&#58;&#99;&#x6f;&#x6d;&#112;&#x6f;&#117;&#110;&#x64;&#106;&#115;&#64;&#103;&#111;&#x6f;&#x67;&#108;&#x65;&#x67;&#114;&#x6f;&#117;&#x70;&#115;&#x2e;&#x63;&#111;&#109;" data-bare-link="true">&#x63;&#x6f;&#x6d;&#112;&#x6f;&#117;&#x6e;&#x64;&#x6a;&#x73;&#x40;&#103;&#x6f;&#111;&#103;&#x6c;&#101;&#103;&#x72;&#111;&#x75;&#112;&#x73;&#x2e;&#99;&#111;&#x6d;</a></dd>
+<dt class="flush">email</dt><dd><a href="&#109;&#97;&#105;&#108;&#116;&#x6f;&#58;&#x63;&#x6f;&#109;&#112;&#111;&#x75;&#x6e;&#x64;&#x6a;&#x73;&#64;&#103;&#x6f;&#111;&#103;&#x6c;&#x65;&#103;&#x72;&#x6f;&#x75;&#x70;&#115;&#46;&#x63;&#111;&#109;" data-bare-link="true">&#x63;&#111;&#x6d;&#x70;&#x6f;&#x75;&#110;&#100;&#x6a;&#x73;&#x40;&#103;&#x6f;&#111;&#x67;&#x6c;&#x65;&#x67;&#x72;&#111;&#117;&#x70;&#115;&#46;&#x63;&#x6f;&#109;</a></dd>
 </dl>
 
 
+<p>Provide test case for reproducing error. When reporting issue to core mention
+adapter where problem could be reproduced.</p>
+
 <h2 id="HISTORY">HISTORY</h2>
 
 <p>See <a class="man-ref" href="changelog.3.html">jugglingdb-changelog<span class="s">(3)</span></a></p>
 
-<h2 id="LICENSE">LICENSE</h2>
+<h2 id="COPYRIGHT">COPYRIGHT</h2>
 
-<p>JugglingDB has MIT license, see <span class="man-ref">jugglingdb-license<span class="s">(3)</span></span> for details.</p>
+<p>JugglingDB is Copyright (C) 2011 Anatoliy Chakkaev http://anatoliy.in</p>
 
 <h2 id="AUTHOR">AUTHOR</h2>
 
@@ -161,7 +188,7 @@ development and see how you can help jugglingdb to grow up.</p>
 <li><a href="https://github.com/1602/">github/1602</a></li>
 <li><a href="https://github.com/anatoliychakkaev/">github/anatoliychakkaev</a></li>
 <li><a href="http://twitter.com/1602">twitter@1602</a></li>
-<li><a href="&#109;&#x61;&#105;&#108;&#116;&#x6f;&#x3a;&#109;&#97;&#x69;&#x6c;&#x40;&#97;&#110;&#x61;&#116;&#x6f;&#x6c;&#105;&#x79;&#x2e;&#105;&#110;" data-bare-link="true">&#x6d;&#97;&#105;&#108;&#x40;&#97;&#110;&#97;&#116;&#x6f;&#108;&#105;&#121;&#x2e;&#x69;&#110;</a></li>
+<li><a href="&#x6d;&#97;&#x69;&#108;&#x74;&#x6f;&#x3a;&#109;&#x61;&#105;&#108;&#x40;&#x61;&#110;&#97;&#116;&#x6f;&#108;&#x69;&#121;&#46;&#105;&#110;" data-bare-link="true">&#109;&#97;&#x69;&#108;&#64;&#97;&#x6e;&#x61;&#116;&#x6f;&#108;&#105;&#121;&#x2e;&#x69;&#x6e;</a></li>
 </ul>
 
 
@@ -170,7 +197,7 @@ development and see how you can help jugglingdb to grow up.</p>
 <h3 id="core-contributors-more-than-1-">core contributors (more than 1%)</h3>
 
 <pre><code>410 Anatoliy Chakkaev       73.9%
- 31 Sébastien Drouyer      5.6%
+ 31 Sebastien Drouyer       5.6%
  25 1602                    4.5%
   9 Muneeb Samuels          1.6%
   6 Henri Bergius           1.1%
@@ -179,10 +206,15 @@ development and see how you can help jugglingdb to grow up.</p>
 <h3 id="adapters-maintainers">adapters maintainers</h3>
 
 <ul>
-<li><a href="https://github.com/jugglingdb/nano-adapter">jugglingdb-nano</a> -- <a href="https://github.com/nrw">Nicholas Westlake</a></li>
+<li><a href="https://github.com/jugglingdb/nano-adapter">jugglingdb-nano</a> - <a href="https://github.com/nrw">Nicholas Westlake</a></li>
+<li><a href="https://github.com/jugglingdb/mysql-adapter">jugglingdb-mysql</a> - <a href="https://github.com/dgsan">dgsan</a></li>
+<li><a href="https://github.com/jugglingdb/firebird-adapter">jugglingdb-firebird</a> - <a href="https://github.com/hgourvest">Henri Gourvest</a></li>
 </ul>
 
 
+<p><em>NOTE:</em> Other adapters waits for their maintainers, drop a line to
+mail@anatoliy.in if you want to maintain some adapter on regular basis.</p>
+
 <h2 id="SEE-ALSO">SEE ALSO</h2>
 
 
diff --git a/docs/index.txt b/docs/index.txt
index e30d28dc..8f84e161 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -1,3 +1,4 @@
+# man pages
 jugglingdb(3)              index
 jugglingdb-changelog(3)    changelog.3
 jugglingdb-roadmap(3)      roadmap.3
@@ -5,5 +6,19 @@ jugglingdb-validations(3)  validations.3
 jugglingdb-hooks(3)        hooks.3
 jugglingdb-schema(3)       schema.3
 jugglingdb-model(3)        model.3
+jugglingdb-adapter(3)      adapter.3
 
+# adapters
 jugglingdb-nano            https://github.com/jugglingdb/nano-adapter
+jugglingdb-mysql           https://github.com/jugglingdb/mysql-adapter
+jugglingdb-firebird        https://github.com/jugglingdb/firebird-adapter
+jugglingdb-sqlite3         https://github.com/jugglingdb/sqlite3-adapter
+jugglingdb-postgres        https://github.com/jugglingdb/postgres-adapter
+jugglingdb-redis           https://github.com/jugglingdb/redis-adapter
+jugglingdb-mongodb         https://github.com/jugglingdb/mongodb-adapter
+
+# external resources
+github.com/jugglingdb      https://github.com/jugglingdb
+github.com/1602/jugglingdb https://github.com/1602/jugglingdb
+issues                     https://github.com/1602/jugglingdb/issues?state=open
+jsdoc.info/1602/jugglingdb http://jsdoc.info/1602/jugglingdb
diff --git a/docs/jugglingdb.md b/docs/jugglingdb.md
index d2fcc1d1..3e2815ef 100644
--- a/docs/jugglingdb.md
+++ b/docs/jugglingdb.md
@@ -29,7 +29,8 @@ See jugglingdb-adapters(3) for list of available adapters.
 
 ## DOCUMENTATION
 
-Autogenerated documentation available at [jsdoc.info/1602/jugglingdb](https://jsdoc.info/1602/jugglingdb). Human-written manual sections are:
+Autogenerated documentation available at [jsdoc.info/1602/jugglingdb].
+Human-written manual sections are:
 
 * jugglingdb-schema(3):
   Everything about schema, data types and model definition.
@@ -44,10 +45,26 @@ Autogenerated documentation available at [jsdoc.info/1602/jugglingdb](https://js
 * jugglingdb-hooks(3):
   Hooks and object lifecycle.
 
+* jugglingdb-adapter(3):
+  Adapter API explained.
+
 ## ADAPTERS
 
+All adapters available as separate packages at
+[github.com/jugglingdb] and published in npm.
+
+* [jugglingdb-mysql]
+* [jugglingdb-sqlite3]
+* [jugglingdb-postgres]
+* [jugglingdb-redis]
+* [jugglingdb-mongodb]
+* [jugglingdb-nano]
+* [jugglingdb-firebird]
+
 ## CONTRIBUTION
 
+TODO: briefly describe contribution
+
 ## FUTURE
 
 See jugglingdb-roadmap(3) and [github issues][issues] to catch up current
@@ -64,13 +81,16 @@ When you find issues, please report them:
 * email:
   <compoundjs@googlegroups.com>
 
+Provide test case for reproducing error. When reporting issue to core mention
+adapter where problem could be reproduced.
+
 ## HISTORY
 
 See jugglingdb-changelog(3)
 
-## LICENSE
+## COPYRIGHT
 
-JugglingDB has MIT license, see jugglingdb-license(3) for details.
+JugglingDB is Copyright (C) 2011 Anatoliy Chakkaev http://anatoliy.in
 
 ## AUTHOR
 
@@ -84,7 +104,7 @@ JugglingDB has MIT license, see jugglingdb-license(3) for details.
 
 ### core contributors (more than 1%)
     410	Anatoliy Chakkaev       73.9%
-     31	Sébastien Drouyer      5.6%
+     31	Sebastien Drouyer       5.6%
      25	1602                    4.5%
       9	Muneeb Samuels          1.6%
       6	Henri Bergius           1.1%
diff --git a/docs/model.md b/docs/model.md
new file mode 100644
index 00000000..b0d12c87
--- /dev/null
+++ b/docs/model.md
@@ -0,0 +1,15 @@
+jugglingdb-model(3) - Model methods, features and internals
+===================
+
+## DESCRIPTION
+
+This section describes common methods of models managed by jugglingdb and
+explains some model internals, such as data representation, setters, getters and
+virtual attributes.
+
+## SEE ALSO
+
+jugglingdb-schema(3)
+jugglingdb-validations(3)
+jugglingdb-hooks(3)
+jugglingdb-adapter(3)
diff --git a/docs/schema.md b/docs/schema.md
new file mode 100644
index 00000000..6e801eda
--- /dev/null
+++ b/docs/schema.md
@@ -0,0 +1,126 @@
+jugglingdb-schema(3) - Everything about schema, data types and model definition.
+====================
+
+## DESCRIPTION
+
+Schema is a factory for classes. Schema connected with specific database using
+adapter. 
+
+All classes within single schema shares same adapter type and one database
+connection. But it's possible to use more than one schema to connect with
+different databases.
+
+## EVENTS
+
+Instances of Schema are event emitters, events supported by default:
+
+* `.on('connected', function() {})`:
+  Fired when db connection established. Params: none.
+* `.on('log', function(msg, duration) {})`:
+  Fired when adapter logged line. Params: String message, Number duration
+
+## USAGE
+
+### Creating schema
+
+`Schema` constructor available on `jugglingdb` module:
+
+    var Schema = require('jugglingdb').Schema;
+
+Schema constructor accepts two arguments. First argument is adapter. It could be
+adapter name or adapter package:
+
+    var schemaByAdapterName = new Schema('memory');
+    var schemaByAdapterPackage = new Schema(require('redis'));
+
+### Settings
+
+Second argument is optional settings. Settings object format and defaults
+depends on specific adapter, but common fields are:
+
+* `host`:
+Database host
+* `port`:
+Database port
+* `username`:
+Username to connect to database
+* `password`:
+Password to connect to database
+* `database`:
+Database name
+* `debug`:
+Turn on verbose mode to debug db queries and lifecycle
+
+For adapter-specific settings refer to adapter's readme file.
+
+### Connecting to database
+
+Schema connecting to database automatically. Once connection established schema
+object emit 'connected' event, and set `connected` flag to true, but it is not
+necessary to wait for 'connected' event because all queries cached and executed
+when schema emit 'connected' event.
+
+To disconnect from database server call `schema.disconnect` method. This call
+forwarded to adapter if adapter have ability to connect/disconnect.
+
+### Model definition
+
+To define model schema have single method `schema.define`. It accepts three
+argumets:
+
+* **model name**:
+  String name in camel-case with first upper-case letter. This name will be used
+  later to access model.
+* **properties**:
+  Object with property type definitions. Key is property name, value is type
+  definition. Type definition can be function representing type of property
+  (String, Number, Date, Boolean), or object with {type: String|Number|...,
+  index: true|false} format.
+* **settings**:
+  Object with model-wide settings such as `tableName` or so.
+
+Examples of model definition:
+
+    var User = schema.define('User', {
+        email: String,
+        password: String,
+        birthDate: Date,
+        activated: Boolean
+    });
+
+    var User = schema.define('User', {
+        email: { type: String, limit: 150, index: true },
+        password: { type: String, limit: 50 },
+        birthDate: Date,
+        registrationDate: {
+            type: Date,
+            default: function () { return new Date }
+        },
+        activated: { type: Boolean, default: false }
+    }, {
+        tableName: 'users'
+    });
+
+### DB structure syncronization
+
+Schema instance have two methods for updating db structure: automigrate and
+autoupdate.
+
+The `automigrate` method drop table (if exists) and create it again,
+`autoupdate` method generates ALTER TABLE query. Both method accepts callback
+called when migration/update done.
+
+To check if any db changes required use `isActual` method. It accepts single
+`callback` argument, which receive boolean value depending on db state: false if
+db structure outdated, true when schema and db is in sync:
+
+    schema.isActual(function(err, actual) {
+        if (!actual) {
+            schema.autoupdate();
+        }
+    });
+
+## SEE ALSO
+
+jugglingdb-model(3)
+jugglingdb-adapter(3)
diff --git a/docs/validations.md b/docs/validations.md
new file mode 100644
index 00000000..edf53dcd
--- /dev/null
+++ b/docs/validations.md
@@ -0,0 +1,2 @@
+jugglingdb-validations(3) - Built-in validators, creating custom validations, syncronous and asyncronous object validation.
+========================
diff --git a/scripts/doc.sh b/scripts/doc.sh
index 505bc6ee..56dca422 100755
--- a/scripts/doc.sh
+++ b/scripts/doc.sh
@@ -20,7 +20,7 @@ case $dest in
 
   *.html)
     ronn -5 $1 --pipe\
-      --style=toc\
+      --style='print toc'\
       --organization=1602\ Software\
       --manual=JugglingDB > $2
     exit $?