From 5c9b2b764098a43a574e2ab45bf8b082d577aac8 Mon Sep 17 00:00:00 2001 From: Charlike Mike Reagent Date: Thu, 1 Nov 2018 05:25:35 +0200 Subject: [PATCH] feat(cli): fixes v0.4 and normalize newlines' Signed-off-by: Charlike Mike Reagent --- .verb.md | 188 +++++++++++++++++++++++++++++++++++++++ README.md | 199 ++++++++++++++++++++++++++++++++++++++++++ package.json | 5 +- src/cli.js | 4 +- src/plugins/render.js | 6 +- 5 files changed, 397 insertions(+), 5 deletions(-) diff --git a/.verb.md b/.verb.md index ca0d7f0..66f3044 100644 --- a/.verb.md +++ b/.verb.md @@ -38,6 +38,194 @@ $ yarn add {%= name %} ## API +_Generated using [docks](http://npm.im/docks)._ + +### [src/index.js](/src/index.js) + +#### [docks](/src/index.js#L47) +Constructor that gives you methods. + +**Returns** +- `Object` instance of `Docks` + +#### [.use](/src/index.js#L79) +A plugin is a function that may extend the core functionality, +or if it returns another function it is called for each block comment. + +Look at [src/plugins/](/src/plugins) folder to see the built-in ones. + +**Params** +- `plugin` **{Function}** with signature like `(docks) => (comment) => {}` + +**Returns** +- `Object` instance of `Docks` + +**Examples** +```javascript +import docks from 'docks'; + +const app = docks(); + +// extending the core +app.use((self) => { + self.foobar = 123 +}); + +console.log(app.foobar); // => 123 + +// Or plugin that will be called on each block comment +app.use(() => (comment) => { + comment.hoho = 'okey' +}); +``` + +#### [.parse](/src/index.js#L112) +Parses given `input` using `@babel/parser` and passes +all block comments to `doctrine` which is JSDoc parser. +It also applies all the "Smart Plugins". Smart plugin is the function +that is returned from each function passed to the `app.use` method. + +**Params** +- `input` **{string}** file content which contains document block comments + +**Returns** +- `Array` an array with `Comment` objects. + +**Examples** +```javascript +const app = docks(); + +const smartPlugin = (comment) => { + // do some stuff witht he Comment object. +}; + +app.use((self) => smartPlugin); + +const cmts = app.parse('some cool stuff with block comments'); +console.log(cmts); +``` + +### [src/plugins/render.js](/src/plugins/render.js) + +#### [.renderFileSync](/src/plugins/render.js#L25) +Render single `fp` file to a documentation string. + +**Params** +- `fp` **{string}** absolute filepath to file to look for doc comments. + +**Returns** +- `string` + +**Examples** +```javascript +const app = docks(); +const output = app.renderFileSync('path/to/source/file/with/comments'); +console.log(output); +``` + +#### [.renderFile](/src/plugins/render.js#L45) +Render single `fp` file to a documentation string, asynchronously. + +**Params** +- `fp` **{string}** absolute file path to look for doc comments. + +**Returns** +- `Promise` + +**Examples** +```javascript +const app = docks(); +app.renderFile('path/to/source/file/with/comments').then((output) => { + console.log(output); +}); +``` + +#### [.renderTextSync](/src/plugins/render.js#L70) +Create a documentation output string from given comments. +Use `app.parse` method to generate such list of `Comment` objects. + +**Params** +- `comments` **{Array<Comment>}** + +**Returns** +- `string` + +**Examples** +```javascript +const app = docks(); + +const comments = app.parse('some string with block comments'); +const output = app.renderTextSync(comments); +console.log(output); +``` + +#### [.renderText](/src/plugins/render.js#L91) +Create a documentation output string from given comments, asynchronously. +Use `app.parse` method to generate such list of `Comment` objects. + +**Params** +- `comments` **{Array<Comment>}** + +**Returns** +- `Promise` + +**Examples** +```javascript +const app = docks(); + +const comments = app.parse('some string with block comments'); +app.renderText(comments).then((output) => { + console.log(output); +}); +``` + +#### [.renderSync](/src/plugins/render.js#L115) +Render a list of filepaths to a documentation string. + +**Params** +- `files` **{Array<string>}** list of absolute file paths to look for doc comments. + +**Returns** +- `string` + +**Examples** +```javascript +const proc = require('process'); +const path = require('path'); +const app = docks(); + +const files = ['src/index.js', 'src/bar.js'].map((fp) => { + return path.join(proc.cwd(), fp); +}) + +const output = app.renderSync(files); +console.log(output); +``` + +#### [.render](/src/plugins/render.js#L145) +Render a list of filepaths to a documentation, asynchronously. + +**Params** +- `files` **{Array<string>}** list of absolute file paths to look for doc comments. + +**Returns** +- `Promise` + +**Examples** +```javascript +const proc = require('process'); +const path = require('path'); +const app = docks(); + +const files = ['src/index.js', 'src/bar.js'].map((fp) => { + return path.join(proc.cwd(), fp); +}) + +app.render(files).then((output) => { + console.log(output); +}); +``` + **[back to top](#thetop)** diff --git a/README.md b/README.md index 3238284..51f169c 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,17 @@ Project is [semantically](https://semver.org) & automatically released on [Circl ## Table of Contents - [Install](#install) - [API](#api) + * [src/index.js](#srcindexjs) + + [docks](#docks) + + [.use](#use) + + [.parse](#parse) + * [src/plugins/render.js](#srcpluginsrenderjs) + + [.renderFileSync](#renderfilesync) + + [.renderFile](#renderfile) + + [.renderTextSync](#rendertextsync) + + [.renderText](#rendertext) + + [.renderSync](#rendersync) + + [.render](#render) - [See Also](#see-also) - [Contributing](#contributing) - [Contributors](#contributors) @@ -45,6 +56,194 @@ $ yarn add docks ## API +_Generated using [docks](http://npm.im/docks)._ + +### [src/index.js](/src/index.js) + +#### [docks](/src/index.js#L47) +Constructor that gives you methods. + +**Returns** +- `Object` instance of `Docks` + +#### [.use](/src/index.js#L79) +A plugin is a function that may extend the core functionality, +or if it returns another function it is called for each block comment. + +Look at [src/plugins/](/src/plugins) folder to see the built-in ones. + +**Params** +- `plugin` **{Function}** with signature like `(docks) => (comment) => {}` + +**Returns** +- `Object` instance of `Docks` + +**Examples** +```javascript +import docks from 'docks'; + +const app = docks(); + +// extending the core +app.use((self) => { + self.foobar = 123 +}); + +console.log(app.foobar); // => 123 + +// Or plugin that will be called on each block comment +app.use(() => (comment) => { + comment.hoho = 'okey' +}); +``` + +#### [.parse](/src/index.js#L112) +Parses given `input` using `@babel/parser` and passes +all block comments to `doctrine` which is JSDoc parser. +It also applies all the "Smart Plugins". Smart plugin is the function +that is returned from each function passed to the `app.use` method. + +**Params** +- `input` **{string}** file content which contains document block comments + +**Returns** +- `Array` an array with `Comment` objects. + +**Examples** +```javascript +const app = docks(); + +const smartPlugin = (comment) => { + // do some stuff witht he Comment object. +}; + +app.use((self) => smartPlugin); + +const cmts = app.parse('some cool stuff with block comments'); +console.log(cmts); +``` + +### [src/plugins/render.js](/src/plugins/render.js) + +#### [.renderFileSync](/src/plugins/render.js#L25) +Render single `fp` file to a documentation string. + +**Params** +- `fp` **{string}** absolute filepath to file to look for doc comments. + +**Returns** +- `string` + +**Examples** +```javascript +const app = docks(); +const output = app.renderFileSync('path/to/source/file/with/comments'); +console.log(output); +``` + +#### [.renderFile](/src/plugins/render.js#L45) +Render single `fp` file to a documentation string, asynchronously. + +**Params** +- `fp` **{string}** absolute file path to look for doc comments. + +**Returns** +- `Promise` + +**Examples** +```javascript +const app = docks(); +app.renderFile('path/to/source/file/with/comments').then((output) => { + console.log(output); +}); +``` + +#### [.renderTextSync](/src/plugins/render.js#L70) +Create a documentation output string from given comments. +Use `app.parse` method to generate such list of `Comment` objects. + +**Params** +- `comments` **{Array<Comment>}** + +**Returns** +- `string` + +**Examples** +```javascript +const app = docks(); + +const comments = app.parse('some string with block comments'); +const output = app.renderTextSync(comments); +console.log(output); +``` + +#### [.renderText](/src/plugins/render.js#L91) +Create a documentation output string from given comments, asynchronously. +Use `app.parse` method to generate such list of `Comment` objects. + +**Params** +- `comments` **{Array<Comment>}** + +**Returns** +- `Promise` + +**Examples** +```javascript +const app = docks(); + +const comments = app.parse('some string with block comments'); +app.renderText(comments).then((output) => { + console.log(output); +}); +``` + +#### [.renderSync](/src/plugins/render.js#L115) +Render a list of filepaths to a documentation string. + +**Params** +- `files` **{Array<string>}** list of absolute file paths to look for doc comments. + +**Returns** +- `string` + +**Examples** +```javascript +const proc = require('process'); +const path = require('path'); +const app = docks(); + +const files = ['src/index.js', 'src/bar.js'].map((fp) => { + return path.join(proc.cwd(), fp); +}) + +const output = app.renderSync(files); +console.log(output); +``` + +#### [.render](/src/plugins/render.js#L145) +Render a list of filepaths to a documentation, asynchronously. + +**Params** +- `files` **{Array<string>}** list of absolute file paths to look for doc comments. + +**Returns** +- `Promise` + +**Examples** +```javascript +const proc = require('process'); +const path = require('path'); +const app = docks(); + +const files = ['src/index.js', 'src/bar.js'].map((fp) => { + return path.join(proc.cwd(), fp); +}) + +app.render(files).then((output) => { + console.log(output); +}); +``` + **[back to top](#thetop)** diff --git a/package.json b/package.json index 29743d1..c69632e 100644 --- a/package.json +++ b/package.json @@ -4,8 +4,9 @@ "license": "Apache-2.0", "licenseStart": "2018", "scripts": { - "predocs": "yarn build", - "docs": "node dist/cli.js && verb", + "predocks": "yarn build", + "docks": "node dist/cli.js --outfile .verb.md", + "docs": "yarn docks && verb", "lint": "eslint src test --fix --format codeframe", "test": "nyc --require esm asia", "prebuild": "rm -rf dist && mkdir dist", diff --git a/src/cli.js b/src/cli.js index a2a8067..db8cab1 100644 --- a/src/cli.js +++ b/src/cli.js @@ -31,14 +31,14 @@ fastGlob(inputFiles, { ...argv, absolute: true }) const promo = '_Generated using [docks](http://npm.im/docks)._'; const docksStart = ''; const docksEnd = ''; - const content = `${docksStart}\n${promo}${apiContent}\n${docksEnd}`; + const content = `${docksStart}\n${promo}\n\n${apiContent}\n\n${docksEnd}`; if (fs.existsSync(outfile)) { const fileContent = await readFile(outfile, 'utf-8'); if (fileContent.includes(docksStart) && fileContent.includes(docksEnd)) { const idxStart = fileContent.indexOf(docksStart); - const idxEnd = fileContent.indexOf(docksEnd); + const idxEnd = fileContent.indexOf(docksEnd) + docksEnd.length; const apiPart = fileContent.substring(idxStart, idxEnd); const newContent = fileContent.replace(apiPart, content); return writeFile(outfile, newContent); diff --git a/src/plugins/render.js b/src/plugins/render.js index 0a2f591..943ebee 100644 --- a/src/plugins/render.js +++ b/src/plugins/render.js @@ -148,7 +148,7 @@ export default function renderPlugin(app) { const content = await app.renderFile(fp); return content.length > 0 ? `### ${createLink(fp)}\n${content}` : ''; }), - ).then((results) => results.join('\n\n')); + ).then((results) => results.filter(Boolean).join('\n\n')); }, }; } @@ -164,6 +164,10 @@ function escape(val) { } function createRender(comments, fp) { + if (comments.length === 0) { + return ''; + } + const output = []; const link = (c) => (fp ? createLink(fp, c.name, c.loc) : c.name);