From 937c793fd066bd618ad45b9ca67d6cf333c99ed4 Mon Sep 17 00:00:00 2001 From: andrewblond Date: Sun, 31 May 2015 18:42:00 +0300 Subject: [PATCH] Rewrote jsdoc --- lib/{compile.js => compiler.js} | 37 ++++++++----- techs/bemjson-to-html.js | 55 ++++++++++++++----- techs/bh-bundle.js | 94 +++++++++++++++++--------------- techs/bh-commonjs.js | 97 +++++++++++++++++++-------------- 4 files changed, 170 insertions(+), 113 deletions(-) rename lib/{compile.js => compiler.js} (81%) diff --git a/lib/compile.js b/lib/compiler.js similarity index 81% rename from lib/compile.js rename to lib/compiler.js index 32d0caf..e6a042c 100644 --- a/lib/compile.js +++ b/lib/compiler.js @@ -8,23 +8,33 @@ core.path = require.resolve('bh/lib/bh.js'); core.contents = fs.readFileSync(core.path, 'utf-8'); /** - * Compile code of bh module with core and source templates. + * @namespace BHCompiler + */ +module.exports = { + compile: compile +}; + +/** + * Compile code of bh module with core and source templates.

* * The compiled BH module supports CommonJS and YModules. If there is no any modular system in the runtime, * the module will be provided as global variable `BH`. * - * @param {{path: String, contents: String}[]} sources Files with source templates + * @memberof BHCompiler + * + * @param {Array.<{path: String, contents: String}>} sources Files with source templates * @param {Object} opts - * @param {String} opts.filename Path to compiled file - * @param {Boolean} [opts.sourcemap=false] Use inline source maps - * @param {String} [opts.jsAttrName] Use `jsAttrName` option for bh core - * @param {String} [opts.jsAttrScheme] Use `jsAttrScheme` option for bh core - * @param {String} [opts.jsCls] Use `jsCls` option for bh core - * @param {Boolean} [opts.jsElem] Use `jsElem` option for bh core - * @param {String} [opts.scope=template] Scope of the executing code templates - * @param {String[]} [opts.mimic] Names for exports - * @param {Object} [opts.requires] Names for requires to `BH.lib.name` - * @returns {String} compiled code of bh module + * @param {String} opts.filename Path to compiled file. + * @param {Object} [opts.requires] Names for dependencies to `BH.lib.name`. + * @param {String[]} [opts.mimic] Names to export. + * @param {String} [opts.scope=template] Scope to execute templates in. + * @param {Boolean} [opts.sourcemap=false] Include inline source maps. + * @param {String} [opts.jsAttrName] Set `jsAttrName` option for BH core. + * @param {String} [opts.jsAttrScheme] Set `jsAttrScheme` option for BH core. + * @param {String} [opts.jsCls] Set `jsCls` option for BH core. + * @param {Boolean} [opts.jsElem] Set `jsElem` option for BH core. + * @param {Boolean} [opts.escapeContent=false] Set `escapeContent` option for BH core. + * @returns {String} compiled code of BH module */ function compile(sources, opts) { opts || (opts = {}); @@ -126,6 +136,7 @@ function compile(sources, opts) { /** * Compile code with YModule definition that exports `BH` module. * + * @ignore * @param {String} name Module name * @param {Object} [requires] Names for requires to `bh.lib.name`. * @returns {String} @@ -166,5 +177,3 @@ function compileYModule(name, requires) { ' });' ].join(EOL); } - -module.exports = compile; diff --git a/techs/bemjson-to-html.js b/techs/bemjson-to-html.js index 0770126..a642589 100644 --- a/techs/bemjson-to-html.js +++ b/techs/bemjson-to-html.js @@ -1,25 +1,50 @@ +var requireOrEval = require('enb/lib/fs/require-or-eval'), + asyncRequire = require('enb/lib/fs/async-require'), + dropRequireCache = require('enb/lib/fs/drop-require-cache'); + /** - * bemjson-to-html - * ================= + * @class BemjsonToHtmlTech + * @augments {BaseTech} + * @classdesc + * + * Build HTML file.

+ * + * This tech uses `BH.apply(bemjson)` to build HTML. * - * Собирает *html*-файл с помощью *bemjson* и *BH*. + * @param {Object} [options] Options + * @param {String} [options.target='?.html'] Path to target with HTML file. + * @param {String} [options.bhFile='?.bh.js'] Path to file with compiled BH module. + * @param {String} [options.bemjsonFile='?.bemjson.js'] Path to file with BEMJSON file. * - * **Опции** + * @example + * var BemjsonToHtmlTech = require('enb-bh/techs/bemjson-to-html'), + * BHCommonJSTech = require('enb-bh/techs/bh-commonjs'), + * FileProvideTech = require('enb/techs/file-provider'), + * bem = require('enb-bem-techs'); * - * * *String* **bhFile** — Исходный BH-файл. По умолчанию — `?.bh.js`. - * * *String* **bemjsonFile** — Исходный BEMJSON-файл. По умолчанию — `?.bemjson.js`. - * * *String* **target** — Результирующий HTML-файл. По умолчанию — `?.html`. + * module.exports = function(config) { + * config.node('bundle', function(node) { + * // get BEMJSON file + * node.addTech([FileProvideTech, { target: '?.bemjson.js' }]); * - * **Пример** + * // get FileList + * node.addTechs([ + * [bem.levels, levels: ['blocks']], + * bem.bemjsonToBemdecl, + * bem.deps, + * bem.files + * ]); * - * ```javascript - * nodeConfig.addTech(require('enb-bh/techs/bemjson-to-html')); - * ``` + * // build BH file + * node.addTech(BHCommonJSTech); + * node.addTarget('?.bh.js'); + * + * // build HTML file + * node.addTech(BemjsonToHtmlTech); + * node.addTarget('?.html'); + * }); + * }; */ -var requireOrEval = require('enb/lib/fs/require-or-eval'), - asyncRequire = require('enb/lib/fs/async-require'), - dropRequireCache = require('enb/lib/fs/drop-require-cache'); - module.exports = require('enb/lib/build-flow').create() .name('bemjson-to-html') .target('target', '?.html') diff --git a/techs/bh-bundle.js b/techs/bh-bundle.js index 381cc83..9624a95 100644 --- a/techs/bh-bundle.js +++ b/techs/bh-bundle.js @@ -1,49 +1,56 @@ +var vow = require('vow'), + vfs = require('enb/lib/fs/async-fs'), + compile = require('../lib/compiler').compile; + /** - * bh-bundle - * ========= - * - * Склеивает *BH*-файлы по deps'ам в виде `?.bh.js` бандла. + * @class BHBundleTech + * @augments {BaseTech} + * @classdesc * - * Предназначен для сборки как клиентского, так и серверного BH-кода. - * Предполагается, что в *BH*-файлах не используется `require`. + * Build file with commonJS requires for core and each bh template (bh.js files).

* - * Поддерживает CommonJS и YModules. Если в исполняемой среде нет ни одной модульной системы, то модуль будет - * предоставлен в глобальную переменную `bh`. + * Use to apply in browsers and on server side (Node.js).

* - * **Опции** + * The compiled BH module supports CommonJS and YModules. If there is no any modular system in the runtime, + * the module will be provided as global variable `BH`.

* - * * *String* **target** — Результирующий таргет. По умолчанию — `?.bh.js`. - * * *String* **filesTarget** — files-таргет, на основе которого получается список исходных файлов - * (его предоставляет технология `files`). По умолчанию — `?.files`. - * * *String* **sourceSuffixes** — суффиксы файлов, по которым строится `files`-таргет. По умолчанию — ['bh.js']. - * * *Boolean* **sourcemap** — строить карты кода. - * * *String* **scope** — скоуп выполнения кода шаблонов. По умолчанию — `template`. Если значение равно `template`, - * то каждый шаблон будет выполнен в своём отдельном скоупе. Если значение равно `global`, - * то все шаблоны будут выполнены в общем скоупе. - * * *String|Array* **mimic** — имена переменных/модулей для экспорта. - * * *String* **jsAttrName** — атрибут блока с параметрами инициализации. По умолчанию — `data-bem`. - * * *String* **jsAttrScheme** — Cхема данных для параметров инициализации. По умолчанию — `json`. - * * Форматы: - * * `js` — Получаем `return { ... }`. - * * `json` — JSON-формат. Получаем `{ ... }`. + * Important: do not use `require` in templates. * - * * *String|Boolean* **jsCls** — имя `i-bem` CSS-класса. По умолчанию - `i-bem`. Для того, чтобы класс - * не добавлялся, следует указать значение `false` или пустую строку. - * * *Boolean* **jsElem** — следует ли добавлять `i-bem` класс для элементов. По умолчанию - `true`. - * Для того, чтобы класс не добавлялся, следует указать значение `false`. + * @param {Object} [options] Options + * @param {String} [options.target='?.bh.js'] Path to target with compiled file. + * @param {String} [options.filesTarget='?.files'] Path to target with FileList. + * @param {String[]} [options.sourceSuffixes='bh.js'] Files with specified suffixes involved in the assembly. + * @param {Object} [options.requires] Names for dependencies to `BH.lib.name`. + * @param {String[]} [options.mimic] Names to export. + * @param {String} [options.scope='template'] Scope to execute templates in. + * @param {Boolean} [options.sourcemap=false] Include inline source maps. + * @param {String} [options.jsAttrName='data-bem'] Set `jsAttrName` option for BH core. + * @param {String} [options.jsAttrScheme='json'] Set `jsAttrScheme` option for BH core. + * @param {String} [options.jsCls='i-bem'] Set `jsCls` option for BH core. + * @param {Boolean} [options.jsElem=true] Set `jsElem` option for BH core. + * @param {Boolean} [options.escapeContent=false] Set `escapeContent` option for BH core. * - * * *Boolean* **escapeContent** — экранирование содержимого. По умолчанию - `false`. + * @example + * var BHBundleTech = require('enb-bh/techs/bh-bundle'), + * FileProvideTech = require('enb/techs/file-provider'), + * bem = require('enb-bem-techs'); * - * **Пример** + * module.exports = function(config) { + * config.node('bundle', function(node) { + * // get FileList + * node.addTechs([ + * [FileProvideTech, { target: '?.bemdecl.js' }], + * [bem.levels, levels: ['blocks']], + * bem.deps, + * bem.files + * ]); * - * ```javascript - * nodeConfig.addTech(require('enb-bh/techs/bh-bundle')); - * ``` + * // build BH file + * node.addTech(BHBundleTech); + * node.addTarget('?.bh.js'); + * }); + * }; */ -var vow = require('vow'), - vfs = require('enb/lib/fs/async-fs'), - compile = require('../lib/compile'); - module.exports = require('enb/lib/build-flow').create() .name('bh-bundle') .target('target', '?.bh.js') @@ -63,13 +70,14 @@ module.exports = require('enb/lib/build-flow').create() return this._compile(sources); }, this); }) - .methods({ + .methods(/** @lends BHBundleTech.prototype */{ /** * Compile code of bh module with core and source templates. * - * @param {{path: String, contents: String}[]} sources Files with source templates - * @returns {String} compiled code of bh module + * @see BHCompiler.compile * @protected + * @param {Array.<{path: String, contents: String}>} sources - Files with source templates. + * @returns {String} compiled code of bh module */ _compile: function (sources) { var opts = { @@ -90,9 +98,9 @@ module.exports = require('enb/lib/build-flow').create() /** * Read files with source templates. * - * @param {FileList} files - * @returns {{ path: String, relPath: String, contents: String }[]} * @protected + * @param {FileList} files + * @returns {Array.<{path: String, relPath: String, contents: String}>} */ _readTemplates: function (files) { var node = this.node, @@ -112,9 +120,9 @@ module.exports = require('enb/lib/build-flow').create() /** * Adapts single BH file content to client-side. * - * @param {String} contents - * @returns {String} * @protected + * @param {String} contents - Contents of source file. + * @returns {String} */ _processTemplate: function (contents) { return contents diff --git a/techs/bh-commonjs.js b/techs/bh-commonjs.js index d3419df..c6420fc 100644 --- a/techs/bh-commonjs.js +++ b/techs/bh-commonjs.js @@ -1,42 +1,50 @@ +var coreFilename = require.resolve('bh/lib/bh.js'), + EOL = require('os').EOL; + /** - * bh-commonjs - * =========== + * @class BHCommonJSTech + * @augments {BaseTech} + * @classdesc * - * Склеивает *BH*-файлы по deps'ам с помощью набора `require` в виде `?.bh.js`. - * Предназначен для сборки серверного BH-кода. После сборки требуется наличия всех файлов, - * подключённых с помощью набора `require`. + * Compile CommonJS module of BH with requires of core and source templates (bh.js files).

* - * **Опции** + * Use to apply in server side only (Node.js). You can use `require` in templates.

* - * * *String* **target** — Результирующий таргет. По умолчанию — `?.bh.js`. - * * *String* **filesTarget** — files-таргет, на основе которого получается список исходных файлов - * (его предоставляет технология `files`). По умолчанию — `?.files`. - * * *String* **sourceSuffixes** — суффиксы файлов, по которым строится `files`-таргет. По умолчанию — ['bh.js']. - * * *String|Array* **mimic** — имена модулей для экспорта. - * * *Boolean* **devMode** — режим сборки. По умолчанию — `true`. - * * *String* **jsAttrName** — атрибут блока с параметрами инициализации. По умолчанию — `data-bem`. - * * *String* **jsAttrScheme** — Cхема данных для параметров инициализации. По умолчанию — `json`. - * * Форматы: - * * `js` — значение по умолчанию. Получаем `return { ... }`. - * * `json` — JSON-формат. Получаем `{ ... }`. + * Important: for correct apply the source files and files are specified in `requires` should be in file system. * - * * *String|Boolean* **jsCls** — имя `i-bem` CSS-класса. По умолчанию - `i-bem`. Для того, чтобы класс - * не добавлялся, следует указать значение `false` или пустую строку. - * * *Boolean* **jsElem** — следует ли добавлять `i-bem` класс для элементов. По умолчанию - `true`. - * Для того, чтобы класс не добавлялся, следует указать значение `false`. + * @param {Object} [options] Options + * @param {String} [options.target='?.bh.js'] Path to target with compiled file. + * @param {String} [options.filesTarget='?.files'] Path to target with FileList. + * @param {String[]} [options.sourceSuffixes='bh.js'] Files with specified suffixes involved in the assembly. + * @param {String[]} [options.mimic] Names to export. + * @param {Boolean} [options.devMode=true] Drop cache for `require` of source templates. + * @param {String} [options.jsAttrName='data-bem'] Set `jsAttrName` option for BH core. + * @param {String} [options.jsAttrScheme='json'] Set `jsAttrScheme` option for BH core. + * @param {String} [options.jsCls='i-bem'] Set `jsCls` option for BH core. + * @param {Boolean} [options.jsElem=true] Set `jsElem` option for BH core. + * @param {Boolean} [options.escapeContent=false] Set `escapeContent` option for BH core. * - * * *Boolean* **escapeContent** — экранирование содержимого. По умолчанию - `false`. + * @example + * var BHCommonJSTech = require('enb-bh/techs/bh-commonjs'), + * FileProvideTech = require('enb/techs/file-provider'), + * bem = require('enb-bem-techs'); * - * **Пример** + * module.exports = function(config) { + * config.node('bundle', function(node) { + * // get FileList + * node.addTechs([ + * [FileProvideTech, { target: '?.bemdecl.js' }], + * [bem.levels, levels: ['blocks']], + * bem.deps, + * bem.files + * ]); * - * ```javascript - * nodeConfig.addTech(require('enb-bh/techs/bh-commonjs')); - * ``` + * // build BH file + * node.addTech(BHCommonJSTech); + * node.addTarget('?.bh.js'); + * }); + * }; */ - -var coreFilename = require.resolve('bh/lib/bh.js'), - EOL = require('os').EOL; - module.exports = require('enb/lib/build-flow').create() .name('bh-commonjs') .target('target', '?.bh.js') @@ -50,17 +58,24 @@ module.exports = require('enb/lib/build-flow').create() .useFileList(['bh.js']) .builder(function (bhFiles) { var node = this.node, - devMode = this._devMode; + devMode = this._devMode, + mimic = [].concat(this._mimic); /** - * Генерирует `require`-строку для подключения исходных bh-файлов. + * Compile code for `require` module. + * + * In dev mode will be added code for drop cache of require. * - * @param {String} absPath - * @param {String} pre - * @param {String} post + * @param {String} filename - absolute path to module + * @param {String} varname - variable name to get module */ - function buildRequire(absPath, pre, post) { - var relPath = node.relativePath(absPath); + function compileRequire(varname, filename) { + if (arguments.length === 1) { + filename = varname; + varname = undefined; + } + + var relPath = node.relativePath(filename); // Replace slashes with backslashes for windows paths for correct require work. /* istanbul ignore if */ @@ -70,7 +85,7 @@ module.exports = require('enb/lib/build-flow').create() return [ devMode ? 'dropRequireCache(require, require.resolve("' + relPath + '"));' : '', - (pre || '') + 'require("' + relPath + '")' + (post || '') + ';' + (varname ? 'var ' + varname + '= ' : '') + 'require("' + relPath + '")' + (varname ? '' : '(bh)') + ';' ].join(EOL); } @@ -95,7 +110,7 @@ module.exports = require('enb/lib/build-flow').create() return [ devMode ? dropRequireCacheFunc : '', - buildRequire(coreFilename, 'var BH = '), + compileRequire('BH', coreFilename), 'var bh = new BH();', 'bh.setOptions({', ' jsAttrName: \'' + this._jsAttrName + '\',', @@ -106,11 +121,11 @@ module.exports = require('enb/lib/build-flow').create() '});', '', bhFiles.map(function (file) { - return buildRequire(file.fullname, '', '(bh)'); + return compileRequire(file.fullname); }).join(EOL), '', 'module.exports = bh;', - this._mimic ? [].concat(this._mimic).map(function (name) { + mimic.length ? mimic.map(function (name) { return 'bh[\'' + name + '\'] = bh;'; }).join(EOL) : '' ].join(EOL);