From eea87fc7028cf351e4b5e2d92984c9118092512d Mon Sep 17 00:00:00 2001 From: icfr Date: Thu, 22 Sep 2016 20:16:47 +0200 Subject: [PATCH] [feat] Add js doc --- .eslintrc | 19 +++++++++++++++++-- .jsdoc.json | 26 ++++++++++++++++++++++++++ lib/Mail.js | 28 ++++++++++++++++++++++++++-- lib/shell/lib/plugins/router.js | 18 +++++++++++++++++- lib/utils.js | 10 +++++++++- lib/utilsCmd.js | 23 ++++++++++++++++++++++- package.json | 7 ++++++- 7 files changed, 123 insertions(+), 8 deletions(-) create mode 100644 .jsdoc.json diff --git a/.eslintrc b/.eslintrc index 48b1192..48d1166 100644 --- a/.eslintrc +++ b/.eslintrc @@ -1,6 +1,8 @@ ecmaFeatures: modules: true +#plugins: ["jsdoc"] + env: amd: true es6: true @@ -9,7 +11,7 @@ env: # http://eslint.org/docs/rules/ rules: # Possible Errors - comma-dangle: [2, never] + comma-dangle: [2, "never"] no-cond-assign: 2 no-console: 0 no-constant-condition: 2 @@ -25,7 +27,7 @@ rules: no-extra-parens: 2 no-extra-semi: 2 no-func-assign: 2 - no-inner-declarations: [2, functions] + no-inner-declarations: [2, "functions"] no-invalid-regexp: 2 no-irregular-whitespace: 2 no-negated-in-lhs: 2 @@ -207,3 +209,16 @@ rules: prefer-spread: 0 prefer-template: 0 require-yield: 0 + + #jsdoc + // jsdoc/check-param-names: 0 + // jsdoc/check-tag-names: 1 + // jsdoc/check-types: 1 + // jsdoc/newline-after-description: 1 + // jsdoc/require-description-complete-sentence: 1 + // jsdoc/require-hyphen-before-param-description: 1 + // jsdoc/require-param: 1 + // jsdoc/require-param-description: 1 + // jsdoc/require-param-type: 1 + // jsdoc/require-returns-description: 1 + // jsdoc/require-returns-type: 1 diff --git a/.jsdoc.json b/.jsdoc.json new file mode 100644 index 0000000..6616131 --- /dev/null +++ b/.jsdoc.json @@ -0,0 +1,26 @@ +{ + "tags": { + "allowUnknownTags": true, + "dictionaries": ["jsdoc"] + }, + "source": { + "include": ["./", "package.json", "readme.md"], + "includePattern": ".js$", + "excludePattern": "(node_modules/|docs/|test/)" + }, + "plugins": [ + "plugins/markdown" + ], + "templates": { + "cleverLinks": false, + "monospaceLinks": true, + "useLongnameInNav": false + }, + "opts": { + "destination": "/var/www/docs/", + "encoding": "utf8", + "private": true, + "recurse": true, + "template": "./node_modules/minami" + } +} \ No newline at end of file diff --git a/lib/Mail.js b/lib/Mail.js index bf7d1e1..83ba34c 100644 --- a/lib/Mail.js +++ b/lib/Mail.js @@ -1,6 +1,7 @@ 'use strict'; /* global appdir,config,mailer */ // var console = require('debug-logger')('backworker:sendmail'); + var Promise = require('bluebird'); var ECT = require('ect'); var defaults = require('lodash/defaults'); @@ -9,7 +10,26 @@ var renderer = ECT({ root: appdir + '/resources/views/', ext: '.ect' }); - +/** + * @constructor + * @class + * @classdesc send email compiled with ECT via {@link https://github.com/nodemailer/nodemailer|nodemailer} + * @param {string} email email to send to + * @param {string} subject email subject + * @param {Object} data data to pass to ECT + * @param {string} template template relative to resources/views/templates + * @param {Object} options option added to mail + * see {@link https://github.com/nodemailer/nodemailer#e-mail-message-fields|nodemailer email message fields} + * @example + * var Mail = require('laravel-queue/lib/Mail'); + * var mail = new Mail('email@example.com', 'subject',{}, 'example'); + * mail.send() + * .then(function mailSuccess(res) { + * // mail send succeffuly + * }).catch(function mailError() { + * // mail not send + * }); + */ var Mail = function Mail(email, subject, data, template, options) { if (!config.mail) { throw new Error('mail not configured'); @@ -21,7 +41,11 @@ var Mail = function Mail(email, subject, data, template, options) { this.template = template; this.options = options; }; - +/** + * send email + * @param {Function} callback callback called when send + * @return {Promise} Bluebird promise + */ Mail.prototype.send = function sendMail(callback) { var mailTemplate = 'templates/' + this.template + '.ect'; var html = renderer.render(mailTemplate, this.content); diff --git a/lib/shell/lib/plugins/router.js b/lib/shell/lib/plugins/router.js index 66a9f4a..1a2abc9 100644 --- a/lib/shell/lib/plugins/router.js +++ b/lib/shell/lib/plugins/router.js @@ -49,6 +49,13 @@ var match = function match(req, routes) { return routeOk; }; +/** + * Module to find command to run. + * + * @module shell/plugins/router + * @param {Object} settings - Setting of router. + * @returns {void} Return void. + */ module.exports = function router(settings) { var params, routes, shell; shell = settings.shell; @@ -70,7 +77,16 @@ module.exports = function router(settings) { } return this; }; - shell.cmd = function shellCmd(command, description, middleware1, middleware2, fn) { + /** + * Add route to shell. + * + * @function cmd + * @param {string} command - Command format example: "command_name :required_arg :optional_arg?". + * @param {string=} description - Text show in help. + * @param {...function} middleware - Function to run. + * @returns {Shell} - Return this shell. + */ + shell.cmd = function shellCmd() { var args, keys, route; args = Array.prototype.slice.call(arguments); route = {}; diff --git a/lib/utils.js b/lib/utils.js index 96c7b57..f7aca38 100644 --- a/lib/utils.js +++ b/lib/utils.js @@ -3,8 +3,16 @@ var fs = require('fs'); var path = require('path'); var existsSync = fs.existsSync; - +/** + * function utils + * @module lib/utils + */ module.exports = { + /** + * find app dir + * + * @return {string} app dir + */ workspace: function workspace() { var dir, dirs, _i, _len; if (process.env.PWD && existsSync(process.env.PWD)) { diff --git a/lib/utilsCmd.js b/lib/utilsCmd.js index c8315d1..1f58e31 100644 --- a/lib/utilsCmd.js +++ b/lib/utilsCmd.js @@ -4,7 +4,10 @@ var jsBeautify = require('js-beautify').js_beautify; var each = require('lodash/each'); - +/** + * function used in command + * @module lib/utilsCmd + */ module.exports = { flatten: function flatten(arrayIn, ret) { if (typeof ret === 'undefined') { @@ -19,6 +22,11 @@ module.exports = { }) return ret; }, + /** + * format object using jsBeautify + * @param {Object} config configuration object + * @return {string} indented string + */ formatConfig: function formatConfig(config) { if (typeof config !== 'string') { config = JSON.stringify(config); @@ -28,11 +36,24 @@ module.exports = { .replace(/\\\//g, '/'); return config; }, + /** + * display message from array + * @param {Array} result array of message + * @param {Response} res response from command function + * @returns {void} return void + * + */ displayMessage: function displayMessage(result, res) { each(result, function eachMessage(message) { res.green(message).ln(); }); }, + /** + * Display message from error. + * @param {Error} err Array of message. + * @param {Response} res Response from command function. + * @return {void} Return void. + */ displayError: function catchError(err, res) { res.red(err.message).ln(); /* istanbul ignore if*/ diff --git a/package.json b/package.json index ccc5434..2409d0a 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,9 @@ "scripts": { "pretest": "./test/scripts/clean.sh", "test": "istanbul cover nodeunit -- test/ --reporter nested", - "postinstall": "./scripts/install.sh" + "posttest": "./test/scripts/clean.sh", + "postinstall": "./scripts/install.sh", + "gen-docs": "jsdoc --configure .jsdoc.json --verbose" }, "bin": { "artisan": "./bin/artisan", @@ -54,5 +56,8 @@ "sequelize": "^3.24.3", "shelljs": "^0.7.4", "tmp": "0.0.28" + }, + "devDependencies": { + "minami": "^1.1.1" } }