added documentation

Author: Hovhannes Babayan

.gitignore

@@ -8,3 +8,4 @@ node_modules
 
 # coverage reporter output
 coverage
+docs

README.md

@@ -1,12 +1,83 @@
 # attask-api
-[![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![MIT License][license-image]][license-url] [![Build Status][travis-image]][travis-url] [![Coverage][coveralls-image]][coveralls-url]
+[![NPM version][npm-version-image]][npm-url] [![NPM downloads][npm-downloads-image]][npm-url] [![Apache v2 License][license-image]][license-url] [![Build Status][travis-image]][travis-url] [![Coverage][coveralls-image]][coveralls-url]
 
 An AtTask API for the Node and Web
 
+
+## Status
+
+This is currently work in progress. Package will be published to NPM registry once everything will be ready. Use source code at your own risk.
+
+
 ## Usage
 
-This is currently work in progress. Do not try to use this in development or production.
-This section will be updated and package will be published to NPM registry once everything will be ready.
+#### Server-side usage
+
+Install as a dev dependency:
+	
+    npm install attask-api --save-dev
+	
+Then `require('attask-api')` in your code. For example:
+```javascript
+var attask = require('attask-api'),
+	util = require('util');
+
+/**
+ * The console.log statement below will output the following:
+ * { 
+ *    Api: [Function: Api],
+ *    ApiFactory: [Object],
+ *    ApiUtil: [Object],
+ *    ApiConstants: [Object] 
+ * }
+ */
+console.log(util.inspect(attask, {depth:0})); 
+```
+
+#### In a browser
+
+This package uses [Browserify](http://browserify.org) to generate [dist/attask.min.js](dist/attask.min.js). Loading that script will create `window.AtTask` object which will contain all the classes and methods just as in the server-side environment (see [Server-side usage](#server-side-usage) section).  
+This package makes use of [Promises](https://www.promisejs.org). Promises are not currently supported by all browsers (see [kangax compatibility tables](http://kangax.github.io/compat-table/es6/#Promise) but there are many polyfills available, including one listed in [www.promisejs.org](https://www.promisejs.org). Load polyfill before `attask.min.js` and everything will work just fine.  
+Although the lack of CORS support may prevent you from sending request to AtTask servers, there are some usage examples in [examples/browser](examples/browser) folder to give you an idea.
+
+
+## Documentation
+
+API documentation is available at [http://bhovhannes.github.io/attask-api/](http://bhovhannes.github.io/attask-api/).
+
+
+## Examples
+
+A number of examples can be found under [examples](examples) directory. It includes examples for both [node](examples/node) and [browser](examples/browser) environments.  
+In order to run these examples clone a copy of attask-api repository:
+
+    git clone git://github.com/bhovhannes/attask-api.git
+
+#### Running [node](examples/node) examples
+
+First enter into `attask-api` directory and install all the dependencies:
+
+    cd attask-api
+    npm install
+
+Use `node` to run the examples. For examples:
+
+    node examples/node/get-use-count.js
+
+Each example script outputs all its results into console and contains comments in the source code explaining what is happenning in more details.
+
+#### Running [browser](examples/browser) examples
+
+There is a separate [Gulp](http://gulpjs.com) task for starting web server.
+To start webserver type:
+
+    node ./node_modules/gulp/bin/gulp.js serve
+
+or, if you have Gulp installed globally, just:
+
+    gulp serve
+
+Visit [http://localhost:8000/examples/browser/](http://localhost:8000/examples/browser/) to see list of all examples available for browser.
 
 
 [license-image]: http://img.shields.io/badge/license-APv2-blue.svg?style=flat

gulpfile.js

@@ -1,18 +1,22 @@
 var gulp = require('gulp');
 
 const BUILD_DIR = './dist/';
+const DOCS_DIR = './docs/';
 const COVERAGE_DIR = 'coverage';
 
 gulp.task('default', ['build']);
 
-gulp.task('clean', ['clean-coverage', 'clean-build']);
+/**
+ * Empties BUILD_DIR, DOCS_DIR and cleans coverage data
+ */
+gulp.task('clean', ['clean-coverage', 'clean-build', 'clean-docs']);
 
 /**
  * Empties BUILD_DIR
  */
 gulp.task('clean-build', function(cb) {
 	var del = require('del');
-	del([BUILD_DIR + '*', COVERAGE_DIR], cb);
+	del([BUILD_DIR + '*'], cb);
 });
 
 /**
@@ -23,6 +27,14 @@ gulp.task('clean-coverage', function(cb) {
 	del([COVERAGE_DIR], cb);
 });
 
+/**
+ * Empties DOCS_DIR
+ */
+gulp.task('clean-docs', function(cb) {
+	var del = require('del');
+	del([DOCS_DIR + '*'], cb);
+});
+
 
 /**
  * Generates browser-ready version for API in BUILD_DIR
@@ -47,7 +59,30 @@ gulp.task('build', ['clean-build'], function() {
 		.pipe(gulp.dest(BUILD_DIR));
 });
 
+/**
+ * Generate documentation in ./docs/ directory
+ */
+gulp.task('docs', ['clean-docs'], function() {
+	var jsdoc = require("gulp-jsdoc");
+	return gulp.src(["src/**/*.js", "README.md"])
+		.pipe(
+			jsdoc(DOCS_DIR, {
+				path: 'ink-docstrap',
+				systemName: 'AtTask',
+				//footer: "Something",
+				//copyright: "Something",
+				navType: "vertical",
+				theme: "united",
+				linenums: true,
+				collapseSymbols: false,
+				inverseNav: false
+			})
+		)
+});
 
+/**
+ * Opens web server in a project directory
+ */
 gulp.task('serve', function() {
 	var webserver = require('gulp-webserver');
 	gulp.src('./')
@@ -61,14 +96,20 @@ gulp.task('serve', function() {
 });
 
 
-var runMocha = function() {
+var runTests = function() {
 	var mocha = require('gulp-mocha');
 	return gulp.src('test/**/*Spec.js', {read: false})
 		.pipe(mocha({}));
 };
 
-gulp.task('test', runMocha);
+/**
+ * Runs all tests
+ */
+gulp.task('test', runTests);
 
+/**
+ * Runs all tests with coverage
+ */
 gulp.task('test-coverage', ['clean-coverage'], function(cb) {
 	var mocha = require('gulp-mocha');
 	var istanbul = require('gulp-istanbul');
@@ -77,12 +118,16 @@ gulp.task('test-coverage', ['clean-coverage'], function(cb) {
 		.pipe(istanbul()) // Covering files
 		.pipe(istanbul.hookRequire()) // Force `require` to return covered files
 		.on('finish', function () {
-			runMocha()
+			runTests()
 			.pipe(istanbul.writeReports()) // Creating the reports after tests runned
 			.on('end', cb);
 		});
 });
 
+/**
+ * This intended to be run only on Travis CI.
+ * Runs all tests with coverage, when upload coverage data to coveralls.io
+ */
 gulp.task('test-ci', ['test-coverage'], function() {
 	var coveralls = require('gulp-coveralls');
 	return gulp.src(COVERAGE_DIR + '/lcov.info')

index.js

@@ -1,8 +1,27 @@
 require('promise/polyfill');
 
+/**
+ * Simplifies creation of API instances as singletons
+ * @type {exports}
+ */
 var ApiFactory = require('./src/ApiFactory');
+
+/**
+ * An Api class
+ * @type {exports}
+ */
 var Api = require('./src/Api');
+
+/**
+ * Various utility methods for working with API
+ * @type {exports}
+ */
 var ApiUtil = require('./src/ApiUtil');
+
+/**
+ * Constants to be used when working with API
+ * @type {exports}
+ */
 var ApiConstants = require('./src/ApiConstants');
 
 module.exports = {

package.json

@@ -13,6 +13,7 @@
     "gulp": "^3.8.10",
     "gulp-coveralls": "^0.1.3",
     "gulp-istanbul": "^0.5.0",
+    "gulp-jsdoc": "^0.1.4",
     "gulp-mocha": "^2.0.0",
     "gulp-uglify": "^1.0.2",
     "gulp-webserver": "^0.9.0",

src/Api.js

@@ -1,11 +1,9 @@
 /**
- * Creates new Api instance. Accepts configuration object with the following keys:
- *     hostname {String} - Required. A name of host to connect to
- *     port {String} - Optional. A port on host to connect to. Defaults to 80.
- *     version {String} - Optional. Which version of api to use.
- *                        At the moment of writing can be 1.0, 2.0, 3.0, 4.0, 5.0.
- *                        Pass 'internal' to use AtTask internal API (this is the latest version, maybe unstable)
- * @param {Object} config
+ * Creates new Api instance.
+ * @param {Object} config   An object with the following keys:<br/>
+ *     <code>hostname</code> {String} - Required. A name of host to connect to<br/>
+ *     <code>port</code> {String} - Optional. A port on host to connect to. Defaults to 80.<br/>
+ *     <code>version</code> {String} - Optional. Which version of api to use. At the moment of writing can be 1.0, 2.0, 3.0, 4.0, 5.0. Pass 'internal' to use AtTask internal API (this is the latest version, maybe unstable)
  * @constructor
  */
 function Api(config) {