Skip to content

Commit

Permalink
Rewrote jsdoc
Browse files Browse the repository at this point in the history
  • Loading branch information
andrewblond committed Jun 4, 2015
1 parent 1dfdff5 commit 937c793
Show file tree
Hide file tree
Showing 4 changed files with 170 additions and 113 deletions.
37 changes: 23 additions & 14 deletions lib/compile.js → lib/compiler.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.<br/><br/>
*
* 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 = {});
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -166,5 +177,3 @@ function compileYModule(name, requires) {
' });'
].join(EOL);
}

module.exports = compile;
55 changes: 40 additions & 15 deletions techs/bemjson-to-html.js
View file
Original file line number Diff line number Diff line change
@@ -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.<br/><br/>
*
* 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')
Expand Down
94 changes: 51 additions & 43 deletions techs/bh-bundle.js
View file
Original file line number Diff line number Diff line change
@@ -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).<br/><br/>
*
* Поддерживает CommonJS и YModules. Если в исполняемой среде нет ни одной модульной системы, то модуль будет
* предоставлен в глобальную переменную `bh`.
* Use to apply in browsers and on server side (Node.js).<br/><br/>
*
* **Опции**
* 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`.<br/><br/>
*
* * *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')
Expand All @@ -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 = {
Expand All @@ -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,
Expand All @@ -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
Expand Down
Loading

0 comments on commit 937c793

Please sign in to comment.