docs: smaller code samples, typos, etc

docs/_static/jiodocs.css

@@ -8,6 +8,7 @@
 pre {
   padding-left: 15px;
   padding-righ: 15px;
+  font-size: 0.8em;
 }
 
 

docs/available_storages.rst

@@ -142,7 +142,7 @@ Updating to v2.0
 Replicate Storage
 ^^^^^^^^^^^^^^^^^
 
-Comming soon
+Coming soon
 
 Revision Based Handlers
 -----------------------

docs/complex_queries.rst

@@ -88,8 +88,7 @@ for how to use these methods, in and outside jIO. The module provides:
 
     {
       parseStringToObject: [Function: parseStringToObject],
-      stringEscapeRegexpCharacters:
-                    [Function: stringEscapeRegexpCharacters],
+      stringEscapeRegexpCharacters: [Function: stringEscapeRegexpCharacters],
       select: [Function: select],
       sortOn: [Function: sortOn],
       limit: [Function: limit],
@@ -120,8 +119,7 @@ Basic example:
     var query = 'title: "Document number 1"';
 
     // running the query
-    var result = complex_queries.QueryFactory.
-                                create(query).exec(object_list);
+    var result = complex_queries.QueryFactory.create(query).exec(object_list);
     // console.log(result);
     // [ { "title": "Document number 1", "creator": "John Doe"} ]
 

docs/developers.rst

@@ -4,20 +4,27 @@ For developers
 Quick start
 -----------
 
-To get started with jIO, clone one of the repositories linked in :ref:`Download & Fork <download-fork>`.
+The source repository includes ready-to-use files, so in case you do
+not want to build jIO yourself, just use *jio.js* as well as *complex_queries.js*
+plus the storages and dependencies you need and you will be good to go.
+
+If you want to modify or build jIO yourself, you need to
+
+* Clone from a repository
+
+  ``$ git clone https://github.com/nexedi/jio.git``
 
-To build the library you have to:
+* Install `NodeJS <http://nodejs.org/>`_ (including ``npm``)
 
-* Install `NodeJS <http://nodejs.org/>`_ (including NPM)
-* Install Grunt command line with npm.
+* Install the Grunt command line with ``npm``.
 
   ``# npm -g install grunt-cli``
 
-* Install dev dependencies.
+* Install the dependencies.
   
   ``$ npm install``
 
-* Compile JS/CC parser.
+* Compile the JS/CC parser.
   
   ``$ make`` (until we find out how to compile it with grunt)
 
@@ -25,14 +32,11 @@ To build the library you have to:
   
   ``$ grunt``
 
-The repository also includes the built ready-to-use files, so in case you do
-not want to build jIO yourself, just use *jio.js* as well as *complex_queries.js*
-plus the storages and dependencies you need and you will be good to go.
 
 Naming Conventions
 ------------------
 
-All the code follows these :ref:`JavaScript Naming Conventions <naming-conventions>`.
+All the code follows this :ref:`JavaScript Style Guide <style-guide>`.
 
 How to design your own jIO Storage Library
 ------------------------------------------
@@ -102,15 +106,17 @@ Methods should return the following objects:
 
 * **post()** --> ``success("created", {"id": new_generated_id})``
 
-* **put()**, ``remove``, ``putAttachment`` or ``removeAttachment`` --> ``success(204)``
+* **put()**, **remove()**, **putAttachment()** or **removeAttachment()** --> ``success(204)``
 
 * **get()** --> ``success("ok", {"data": document_metadata})``
 
 * **getAttachment()** -->
 
-  ``success("ok", {"data": binary_string, "content_type": content_type})``
+  .. code-block:: javascript
+
+    success("ok", {"data": binary_string, "content_type": content_type})
     // or
-  ``success("ok", {"data": new Blob([data], {"type": content_type})})``
+    success("ok", {"data": new Blob([data], {"type": content_type})})
 
 * **allDocs()** --> ``success("ok", {"data": row_object})``
 
@@ -132,8 +138,7 @@ Methods should return the following objects:
     // if metadata doesn't promides "_id" -> repair storage state
     success("no_content")
     // or
-    error("conflict", "corrupted",
-          "impossible to repair document or storage")
+    error("conflict", "corrupted", "impossible to repair document or storage")
     // DON'T DESIGN STORAGES IF THERE IS NO WAY
     // TO REPAIR INCOHERENT STATES
 

docs/getting_started.rst

@@ -33,8 +33,7 @@ Getting started
             "paths": {
                 // jio core + dependency
 
-                // the AMD compatible version of sha256.js,
-                // see Download and Fork
+                // the AMD compatible version of sha256.js, see Download and Fork
                 "sha256": "sha256.amd",
                 "rsvp": "rsvp-custom",
                 "jio": "jio",
@@ -97,16 +96,16 @@ You can use one of the ZIP packages, which include all the dependencies and stor
 `Full download (172k) <_static/jio-2.0.0.zip>`_
 `Minified download (87k) <_static/jio-2.0.0-min.zip>`_
 
-or you can create your own set of files using the following links:
+or you can create your own set of files, which are are provided in the above packages and the source repository:
 
 
 Core
 ^^^^
 
-* `sha256.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/sha256.amd.js>`_
-* `rsvp-custom.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/lib/rsvp/rsvp-custom.js>`_, AMD only version: `rsvp-custom.amd.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/lib/rsvp/rsvp-custom.amd.js>`_
-* `jio.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/jio.js>`_
-* `complex_queries.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/complex_queries.js>`_
+* sha256.amd.js
+* rsvp-custom.js, AMD only version: rsvp-custom.amd.js
+* jio.js
+* complex_queries.js
 
 Storage dependencies
 ^^^^^^^^^^^^^^^^^^^^
@@ -121,27 +120,28 @@ Storage dependencies
 Storage connectors
 ^^^^^^^^^^^^^^^^^^
 
-* `localstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/localstorage.js>`_
-* `davstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/davstorage.js>`_
-* `s3storage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/s3storage.js>`_ (depends on sha1, jQuery) (WIP)
-* `xwikistorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/xwikistorage.js>`_ (depends on jQuery) (WIP)
-* `erp5storage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/erp5storage.js>`_ (depends on jQuery) (WIP)
+* localstorage.js
+* davstorage.js
+* s3storage.js (depends on sha1, jQuery) (WIP)
+* xwikistorage.js (depends on jQuery) (WIP)
+* erp5storage.js (depends on jQuery) (WIP)
 * restsqlstorage.js (depends on jQuery) (WIP)
 * mioga2storage.js (depends on jQuery) (WIP)
 
 Storage handlers
 ^^^^^^^^^^^^^^^^
 
-* `indexstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/indexstorage.js>`_ (WIP)
-* `gidstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/gidstorage.js>`_ (WIP)
-* `splitstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/splitstorage.js>`_ (WIP)
+* indexstorage.js (WIP)
+* gidstorage.js (WIP)
+* splitstorage.js (WIP)
 * replicatestorage.js (WIP)
 
 Revision based storage handlers
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* `revisionstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/revisionstorage.js>`_ (depends on sha256) (WIP)
-* `replicaterevisionstorage.js <http://git.erp5.org/gitweb/jio.git/blob_plain/refs/heads/master:/src/jio.storage/replicatestorage.js>`_ (WIP)
+* revisionstorage.js (depends on sha256) (WIP)
+* replicaterevisionstorage.js (WIP)
+
 
 Unit tests
 ^^^^^^^^^^

docs/index.rst

@@ -48,6 +48,6 @@ jIO documentation
     complex_queries
     metadata
     developers
-    naming_conventions
+    style_guide
     authors
 

docs/manage_documents.rst

@@ -141,14 +141,12 @@ To retrieve jIO responses, you have to provide callbacks like this:
 .. code-block:: javascript
 
   jio_instance.post(metadata, [options]).
-      then([responseCallback],
-           [errorCallback],
-           [progressionCallback]);
+      then([responseCallback], [errorCallback], [progressionCallback]);
 
 
-* On command success, ``responseCallback`` will be called with the jIO response as first parameter.
-* On command error, ``errorCallback`` will be called with the jIO error as first parameter.
-* On command notification, ``progressionCallback`` will be called with the storage notification.
+* On command success, ``responseCallback`` is called with the jIO response as first parameter.
+* On command error, ``errorCallback`` is called with the jIO error as first parameter.
+* On command notification, ``progressionCallback`` is called with the storage notification.
 
 Here is a list of responses returned by jIO according to methods and options:
 
@@ -253,7 +251,7 @@ In case of error, the ``errorCallback`` first parameter will look like:
       "statusText": "Not Found",
       "error": "not_found",
       "reason": "document missing",
-      "message": "Unable to get the requseted document"
+      "message": "Unable to get the requested document"
     }
 
 
@@ -261,7 +259,7 @@ In case of error, the ``errorCallback`` first parameter will look like:
 How to store a video on localStorage
 ------------------------------------
 
-The following example shows how to create a new jIO in localStorage and then post a document with two attachments.
+The following example creates a new jIO in localStorage and then posts a document with two attachments.
 
 .. code-block:: javascript
 
@@ -271,6 +269,7 @@ The following example shows how to create a new jIO in localStorage and then pos
       "username": "usr",
       "application_name":"app"
     });
+
     // post the document "metadata"
     jio_instance.post({
       "title"       : "My Video",
@@ -283,6 +282,7 @@ The following example shows how to create a new jIO in localStorage and then pos
         return alert('Error posting the document meta');
       }
       id = response.id;
+
       // post a thumbnail attachment
       jio_instance.putAttachment({
         "_id": id,
@@ -293,6 +293,7 @@ The following example shows how to create a new jIO in localStorage and then pos
         if (err) {
           return alert('Error attaching thumbnail');
         }
+
         // post video attachment
         jio_instance.putAttachment({
           "_id": id,
@@ -309,7 +310,7 @@ The following example shows how to create a new jIO in localStorage and then pos
     });
 
 
-localStorage contents:
+localStorage now contains:
 
 .. code-block:: javascript
 

docs/metadata.rst

@@ -334,8 +334,7 @@ Posting an image
     "creator"    : "Mr. Someone",
     "title"      : "New York City at Night",
     "subject"    : ["New York"],
-    "description": "A photo of New York City " +
-                     "taken just after midnight",
+    "description": "A photo of New York City taken just after midnight",
     "coverage"   : ["New York", "1996-1997"]
   }, callbacks); // send content as attachment
 

docs/naming_conventions.rst → docs/style_guide.rst

@@ -2,17 +2,17 @@
 .. role:: js(code)
    :language: javascript
 
-.. _naming-conventions:
+.. _style-guide:
 
-JavaScript Naming Conventions
-=============================
+JavaScript Style Guide
+======================
 
-This document defines JavaScript naming conventions, which are split into essential, coding and naming conventions.
+This document defines JavaScript style conventions, which are split into essential, coding and naming conventions.
 
 Essential Conventions
 ---------------------
 
-Essential conventions include generic patterns that should be adhered to in order to write *readable*, *consistent* and *maintainable* code.
+Essential conventions include generic patterns that you should adhere to in order to write *readable*, *consistent* and *maintainable* code.
 
 Minimizing Globals
 ^^^^^^^^^^^^^^^^^^
@@ -48,8 +48,8 @@ Using JSLint
 ^^^^^^^^^^^^
 
 `JSLint <http://www.jslint.com/>`_ is a quality tool that inspects code and warns
-about potential problems. It is available online and can also be integrated
-into several development environments, so errors can be highlighted when
+about potential problems. It can be used online and can also be integrated
+into several development environments, so errors can be highlighted while
 writing code.
 
 Before validating your code in JSLint, you should use a code
@@ -82,11 +82,11 @@ Some allowed options are:
 Coding Conventions
 ------------------
 
-Coding conventions include generic patterns that ensure the written code follows certain formatting conventions.
+Coding conventions include generic patterns that ensure the written code is consistently formatted.
 
 
-Uses two-space indentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Using two-space indentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Tabs and 2-space indentation are being used equally. Since a lot of errors on
 JSLint often result from mixed use of space and tab, using 2 spaces throughout
@@ -228,7 +228,6 @@ Bad Example
 
 .. code-block:: javascript
 
-  // [...]
   return {
     "namedFunction": function namedFunction() {
       return;
@@ -239,7 +238,6 @@ Good Example
 
 .. code-block:: javascript
 
-  // [...]
   function namedFunction() {
     return;
   }
@@ -319,8 +317,6 @@ Variable names with multiple words should always use an underscore between them.
 
 Confusing variable names should end with the variable type.
 
-Example
-
 .. code-block:: javascript
 
   // implicit type