diff --git a/cli.js b/cli.js index 3b33471..abb091d 100755 --- a/cli.js +++ b/cli.js @@ -50,7 +50,7 @@ files.forEach(function(filename) { var file; if (verbose) { - process.stderr.write('Processing ' + filename + '...\n'); + process.stderr.write('Info: Processing ' + filename + '...\n'); } try { @@ -63,10 +63,17 @@ files.forEach(function(filename) { } try { - fs.writeFileSync( - filename, - docblox2md.filterDocument(file, options.threshold) - ); + if(!docblox2md.hasPlaceholder(file)){ + if (verbose) { + process.stderr.write('Skip: ' + filename + ' has no docblox2md placeholder.\n'); + } + } else { + var newdata=docblox2md.filterDocument(file, options.threshold); + fs.writeFileSync(filename,newdata); + if (verbose) { + process.stderr.write('OK: '+filename + ' was written\n'); + } + } } catch (e) { process.stderr.write( 'Error: unable to write to ' + filename + ':' + e + '\n' diff --git a/docblox2md.js b/docblox2md.js index 13e4a74..ccbf918 100644 --- a/docblox2md.js +++ b/docblox2md.js @@ -1,6 +1,43 @@ 'use strict'; var fs = require('fs'); +const path = require('path') + +// default config data +var config={ + 'output': { + 'header': { + 'pre': '', + 'item': "`%s`\n", + 'post': '' + }, + 'params': { + 'pre': '\n**Parameters:**\n\n', + 'item': "* `%s` — `%s` — %s\n", // varname, type, description + 'post': '\n' + }, + 'return': { + 'pre': '\n**Return:**\n\n', + 'item': "%s %s\n", + 'post': '' + } + } +} + +// list of optional custom config files to read ... 1st match wins +const aCfgfiles=[ + process.cwd()+'/.docblox2md.js', // in working directory + path.join(process.env.HOME, '/.docblox2md.js'), // in $HOME + path.join(__dirname, '/.docblox2md.js'), // in install dir +]; + +for (var i=0; i 0) { - md.push('\n**Parameters:**\n\n'); - } - for (j = 0; j < params.length; j++) { - md.push( - '* `' - + params[j].name - + '` — `' - + params[j].type - + '`' - + (params[j].desc ? ' — ' + params[j].desc : '') - + '\n' - ); + md.push(config.output.params.pre) + + for (j = 0; j < params.length; j++) { + md.push( + _sprintf( + config.output.params.item, + params[j].name, + params[j].type, + (params[j].desc ? params[j].desc : '') + ) + ) + } + md.push(config.output.params.post) } // Return value if (returnType !== '' || returnDesc !== '') { - md.push('\n**Returns:**'); - if (returnType !== '') { - md.push(' `' + returnType + '`'); - } - if (returnDesc !== '') { - md.push((returnType !== '' ? ' — ' : ' ') + returnDesc + '\n'); - } + md.push(config.output.return.pre) + md.push( + _sprintf( + config.output.return.item, + returnType+' ', + returnDesc+' ' + ) + ), + md.push(config.output.return.post) } // Final empty line @@ -402,6 +476,17 @@ function loadFile(filename, level, threshold) { return out.join(''); } +/** + * Check Markdown document for our placeholders + * + * @param {String} doc Input document + * + * @return {Boolean} + */ +function hasPlaceholder(doc) { + return doc.split(re.mdSplit).length > 1; +} + /** * Filter Markdown document for our placeholders * @@ -457,6 +542,8 @@ module.exports = { blocksToMarkdown: blocksToMarkdown, srcToMarkdown : srcToMarkdown, + hasPlaceholder : hasPlaceholder, + // End-to-end processing filterDocument: filterDocument, };