ro31337#15 Add esdoc

.gitignore

@@ -7,6 +7,9 @@ cheaptaxi*.log
 # nyc test coverage
 .nyc_output
 
+# esdoc
+esdoc
+
 # Logs
 logs
 *.log

DEVELOPMENT.md

@@ -0,0 +1,81 @@
+Development guidelines
+======================
+
+[Esdoc](https://esdoc.org/) is used. Marking your classes/functions with esdoc
+is mandatory. Tests are mandatory.
+
+Format of esdoc
+===============
+
+Sample comment:
+
+```javascript
+/**
+ * [foo description]
+ * @author Roman Pushkin (roman.pushkin@gmail.com)
+ * @date 2016-04-24
+ * @version [version]
+ * @since [since_version_from_package_json]
+ * @param {[type]} a [description]
+ * @param {[type]} par [description]
+ * @return {[type]} [description]
+ */
+function foo(a, par)
+```
+
+All parameters are required for public functions. It's also highly recommended
+to write descriptions for private functions.
+
+Parameter | Description
+------------|--------------
+ `@version` | Function/class version. When you create a file, set it to 1.1. When you edit and delget it, increment minor version, e.g. to 1.2. Increment major version only if you have breaking changes.
+ `@since` | Version parameter from `package.json`
+
+Note that `@version` is not SEMVER. However, `@since` is SEMVER.
+
+See also:
+* [Difference](http://stackoverflow.com/a/32246313/337085) between @version and @since.
+* [Esdoc Tags](https://esdoc.org/tags.html)
+* [Esdoc Tutorial](https://esdoc.org/tutorial.html)
+
+Along with tags described above, these tags are also highly recommended to use:
+
+* `@example` - use to provide API example
+* `@see http://` - use to provide a website link
+* `@extends {ParentClass}` - use to specify parent class
+* `{@link OtherClass}` - use to link documentation between one class and another
+* `@interface` - to mark class as interface
+* `@implements {MyInterface}` - to show that class implements interface
+
+Esdoc editor configuration
+==========================
+
+[dockblockr](https://atom.io/packages/docblockr) plugin is used for Atom (this plugin is also available for Sublime Text).
+
+When using `dockblockr`, there are two essential commands available when you type:
+
+```
+/**
+```
+
+First command is `Enter` (press right after you typed `/**`). Second command is `Tab`. Depending on command you will either generate class/function description, or just a comment. Please note: there is limited support in dockblockr for es6.
+
+Two important settings for docblockr (in Atom: `Cmd+Shift+P` -> `View installed packages` -> `docblockr` -> `Settings`):
+
+* Align tags: no
+* Extra tags: just copy the code below changing your name and email:
+
+```
+@author Roman Pushkin (roman.pushkin\@gmail.com), @date {{date}}, @version ${1:[version]}, @since ${1:[since_version_from_package_json]}
+```
+
+See also: [Configuration section on dockblockr plugin page](https://atom.io/packages/docblockr).
+
+Generate documentation
+======================
+
+```
+npm run esdoc
+```
+
+Command above will automatically generate and open generated documentation in your browser. It's recommended to execute this command every time you create/update docs for your classes.

README.md

@@ -26,3 +26,12 @@ Run
 ```
 npm start
 ```
+
+Documentation
+=============
+
+Command below will generate documentation based on comments from source code:
+
+```
+npm run esdoc
+```

esdoc.json

@@ -0,0 +1,4 @@
+{
+ "source": "./src",
+ "destination": "./esdoc"
+}

package.json

@@ -14,6 +14,7 @@
  "babel-preset-stage-2": "^6.5.0",
  "babel-register": "^6.7.2",
  "dotenv": "^2.0.0",
+ "esdoc": "^0.4.6",
  "eslint": "^2.8.0",
  "eslint-config-airbnb": "^7.0.0",
  "i18n": "^0.8.2",
@@ -28,7 +29,8 @@
  "lint": "eslint src test",
  "cover": "nyc npm run ava",
  "ava": "ava --require babel-register",
- "start": "babel-node ./src/app.js"
+ "start": "babel-node ./src/app.js",
+ "esdoc": "esdoc -c esdoc.json && rm esdoc/package.json && open ./esdoc/index.html"
  },
  "repository": {
  "type": "git",

src/app.js

@@ -1,4 +1,5 @@
-import log from './log';
+import Log from './log';
 import './init';
 
+const log = new Log();
 log.debug(__('app.welcome_banner'));

src/init.js

@@ -1,7 +1,9 @@
 require('dotenv').config();
-import log from './log';
+import Log from './log';
 import i18n from 'i18n';
 
+const log = new Log();
+
 i18n.configure({
  locales: ['en', 'ru'],
  register: global,

src/log.js

@@ -2,23 +2,58 @@ require('dotenv').config();
 import winston from 'winston';
 import moment from 'moment';
 
-const consoleTransport = new (winston.transports.Console)({
- timestamp() {
- return Date.now();
- },
- formatter(options) {
- const date = moment(options.timestamp()).format('YYYY-MM-DD HH:mm:ss');
- const message = options.message || '';
+/**
+ * Logger, based on [winston](https://github.com/winstonjs/winston).
+ * This class configures winston logger by adding two transports:
+ *
+ * **1. Console transport:**
+ *
+ * Output to console starts with `YYYY-MM-DD HH:mm:ss` prefix, and followed by
+ * log level. For example: `[2016-05-23 04:35:01] [info] Something`
+ * Log level is set to `debug` by default.
+ *
+ * **2. File transport:**
+ *
+ * File transport configures winston to redirect logs into specified file
+ * (`LOG_FILE` parameter in `.env`). By default winston writes file
+ * transport logs in json format.
+ *
+ * Note: meta information is skipped in console transport and stored in
+ * log file only.
+ *
+ * @example
+ * const log = new Log();
+ * log.debug('application started');
+ *
+ * @extends {winston.logger}
+ * @author Roman Pushkin ([email protected])
+ * @date 2016-04-23
+ * @see https://github.com/winstonjs/winston
+ * @version 1.1
+ * @since 0.1.0
+ * @return {Object} Instance of logger
+ */
+export default class Log extends winston.Logger {
+ constructor() {
+ const consoleTransport = new (winston.transports.Console)({
+ timestamp() {
+ return Date.now();
+ },
+ formatter(options) {
+ const date = moment(options.timestamp()).format('YYYY-MM-DD HH:mm:ss');
+ const message = options.message || '';
 
- return `[${date}] [${options.level}] ${message}`; // skip meta information
- },
-});
+  return `[${date}] [${options.level}] ${message}`; // skip meta information
+  },
+ });
 
-const fileTransport = new (winston.transports.File)({
- filename: process.env.LOG_FILE,
-});
+ const fileTransport = new (winston.transports.File)({
+  filename: process.env.LOG_FILE,
+ });
 
-module.exports = new (winston.Logger)({
- transports: [consoleTransport, fileTransport],
- level: 'debug',
-});
+ super({
+ transports: [consoleTransport, fileTransport],
+ level: 'debug',
+ });
+ }
+}