fix: add docs

resolves #1

Signed-off-by: Charlike Mike Reagent <olsten.larck@gmail.com>

Author: Charlike Mike Reagent

.verb.md

@@ -33,6 +33,13 @@ For bugs reports and feature requests, [please create an issue][open-issue-url]
 
 Project is [semantically](https://semver.org) & automatically released on [CircleCI][codecoverage-url] with [new-release][] and its [New Release](https://github.com/apps/new-release) GitHub App.
 
+## Highlights
+
+- [Conventional Commits](https://conventionalcommits.org/) compliant
+- Fast and lightweight in few lines of code
+- Infinitely extensible through plugins, [two built-in](#mappers)
+- Collecting mentions from commit message
+- Detection of breaking changes in commit
 
 ## Table of Contents
 <!-- toc -->

README.md

@@ -33,9 +33,20 @@ For bugs reports and feature requests, [please create an issue][open-issue-url]
 
 Project is [semantically](https://semver.org) & automatically released on [CircleCI][codecoverage-url] with [new-release][] and its [New Release](https://github.com/apps/new-release) GitHub App.
 
+## Highlights
+
+- [Conventional Commits](https://conventionalcommits.org/) compliant
+- Fast and lightweight in few lines of code
+- Infinitely extensible through plugins, [two built-in](#mappers)
+- Collecting mentions from commit message
+- Detection of breaking changes in commit
+
 ## Table of Contents
 - [Install](#install)
 - [API](#api)
+  * [.parse](#parse)
+  * [.mappers](#mappers)
+  * [.plugins](#plugins)
 - [Related Projects](#related-projects)
 - [Contributing](#contributing)
 - [Contributors](#contributors)
@@ -52,12 +63,130 @@ $ yarn add parse-commit-message
 
 ## API
 
+### [.parse](src/index.js#L72)
+Parses given `commitMessage` to an object which can be populated with more things if needed, through `plugins`.
+
+Plugins are functions like `(commit) => {}` and can return object with additional
+properties that will be included in the returned "commit" object.
+There are two built-in plugins - `increment` and `mentions` which are exposed
+as array at exposed `plugins` named export.
+The `commit.header` has also a `toString()` method concatinates
+the `header.scope`, `header.type` and `header.subject` properties.
+
+**Params**
+
+* `commitMessage` **{string}**: required, a whole commit message    
+* `plugins` **{Array}**: optional, a list of functions that are passed with `commit` object    
+* `returns` **{Object}**: with `{ header: { type, scope, subject }, body, footer }`  
+
+**Example**
+
+```js
+import { parse } from 'parse-commit-message';
+
+const commit = parse(`fix(crit): some huge change
+
+Some awesome
+body here.
+
+resolves #333
+`);
+
+console.log(commit)
+// => {
+//   header: {
+//     type: 'fix',
+//     scope: 'crit',
+//     subject: 'some huge change'
+//     toString: [Function: toString],
+//   },
+//   body: 'Some awesome\nbody here.',
+//   footer: 'resolves #333',
+// }
+
+console.log(commit.header.toString())
+// => 'fix(crit): some huge change'
+
+// or adding one more plugin to the builtin ones
+const customPlugin = (commit) => {
+  if (commit.header.type === 'fix') {
+    return { fixed: 'yeah' };
+  }
+  return null;
+};
+const commit = parse('fix(wat): foo bar baz', plugins.concat(customPlugin));
+
+console.log(commit.isBreaking) // => false
+console.log(commit.increment) // => 'patch'
+console.log(commit.header); // => { type: 'fix', subject: 'wat', subject: 'foo bar baz' }
+console.log(commit.fixed); // => 'yeah'
+```
+
+### [.mappers](src/index.js#L228)
+An object with all mappers, such as `plugins` array, but named. This objects is like `{ increment, mentions }` where they are plugins that can be passed as second argument to `.parse`.
+
+1. The `mappers.increment` adds `isBreaking` and `increment` properties
+to the final returned "commit" object:
+- `isBreaking` is `Boolean` that indicates if commit is containing `BREAKING CHANGE: ` or
+the `type` of the commit is `break`, `breaking` or `major`
+- `increment` is a `String` that can be `'patch'`, `'minor'` or `'major'`
+2. The `mappers.mentions` adds `mentions` property to the end result object
+- `mentions` is an array of objects like `{ handle: String, mention: String, index: Number }`,
+see [collect-mentions][]
+
+**Example**
+
+```js
+import { parse, mappers } from 'parse-commit-message';
+
+const commit = parse('fix: BREAKING CHANGE: huge refactor', mappers.increment);
+
+console.log(commit);
+// => {
+//   header: { type: 'fix', scope: undefined, subject: 'BREAKING CHANGE: huge refactor' },
+//   body: null,
+//   footer: null,
+//   isBreaking: true,
+//   increment: 'major'
+// }
+
+const str = `feat(whoa): thanks to @foobie for this
+
+awesome @zazzy and @quxie make this release to happen
+
+resolves #123
+`
+const cmt = parse(str, mappers.mentions);
+
+console.log(cmt.header.type); // => 'feat'
+console.log(cmt.header.scope); // => 'whoa'
+console.log(cmt.header.subject); // => 'hanks to @foobie for this'
+console.log(cmt.body); // => 'awesome @zazzy and @quxie make this release to happen'
+console.log(cmt.footer); // => 'resolves #123'
+console.log(cmt.mentions[0]); // => { handle: '@foobie', mention: 'foobie' }
+console.log(cmt.mentions[1]); // => { handle: '@zazzy', mention: 'zazzy' }
+console.log(cmt.mentions[2]); // => { handle: '@quxie', mention: 'quxie' }
+```
+
+### [.plugins](src/index.js#L250)
+A list of all plugins, such as `mappers` but no names, so can be passed directly to the `.parse` as second argument.
+
+**Example**
+
+```js
+import { parse, plugins } from 'parse-commit-message';
+
+const commit = parse('fix: okey', plugins)
+console.log(commit)
+```
+
 **[back to top](#thetop)**
 
 ## Related Projects
 Some of these projects are used here or were inspiration for this one, others are just related. So, thanks for your existance!
 - [asia](https://www.npmjs.com/package/asia): Blazingly fast, magical and minimalist testing framework, for Today and Tomorrow | [homepage](https://github.com/olstenlarck/asia#readme "Blazingly fast, magical and minimalist testing framework, for Today and Tomorrow")
 - [charlike](https://www.npmjs.com/package/charlike): Small, fast, simple and streaming project scaffolder for myself, but not… [more](https://github.com/tunnckoCore/charlike) | [homepage](https://github.com/tunnckoCore/charlike "Small, fast, simple and streaming project scaffolder for myself, but not only. Supports hundreds of template engines through the @JSTransformers API or if you want custom `render` function passed through options")
+- [collect-mentions](https://www.npmjs.com/package/collect-mentions): Collect mentions from a given text string, using battle-tested `mentions-regex` package | [homepage](https://github.com/olstenlarck/collect-mentions "Collect mentions from a given text string, using battle-tested `mentions-regex` package")
 - [gitcommit](https://www.npmjs.com/package/gitcommit): Lightweight and joyful `git commit` replacement. Conventional Commits compliant. | [homepage](https://github.com/tunnckoCore/gitcommit "Lightweight and joyful `git commit` replacement. Conventional Commits compliant.")
 - [new-release](https://www.npmjs.com/package/new-release): A stable alternative to [semantic-release][]. Only handles NPM publishing and nothing… [more](https://github.com/tunnckoCore/new-release#readme) | [homepage](https://github.com/tunnckoCore/new-release#readme "A stable alternative to [semantic-release][]. Only handles NPM publishing and nothing more. For creating GitHub releases use the Semantic Release GitHub App")
 - [xaxa](https://www.npmjs.com/package/xaxa): Zero-config linting, powered by few amazing unicorns, AirBnB & Prettier. | [homepage](https://github.com/olstenlarck/xaxa "Zero-config linting, powered by few amazing unicorns, AirBnB & Prettier.")
@@ -133,5 +262,6 @@ _This file was generated by [verb-generate-readme](https://github.com/verbose/ve
 [open-issue-url]: https://github.com/olstenlarck/parse-commit-message/issues/new
 [author-link]: https://i.am.charlike.online
 
+[collect-mentions]: https://github.com/olstenlarck/collect-mentions
 [new-release]: https://github.com/tunnckoCore/new-release
 [semantic-release]: https://github.com/semantic-release/semantic-release

package.json

@@ -87,6 +87,7 @@
         "gitcommit",
         "new-release",
         "xaxa",
+        "collect-mentions",
         "charlike"
       ]
     },
@@ -98,4 +99,4 @@
       "semantic-release"
     ]
   }
-}
+}

src/index.js

@@ -7,10 +7,68 @@ import arrayify from 'arrayify';
 import collectMentions from 'collect-mentions';
 
 /**
+ * Parses given `commitMessage` to an object which can be populated with
+ * more things if needed, through `plugins`.
  *
- * @param {string} commitMessage required, a whole commit message
- * @param {Array} plugins optional, a list of functions that get passed with `commit` object
+ * Plugins are functions like `(commit) => {}` and can return object with additional
+ * properties that will be included in the returned "commit" object.
+ *
+ * There are two built-in plugins - `increment` and `mentions` which are exposed
+ * as array at exposed `plugins` named export.
+ *
+ * The `commit.header` has also a `toString()` method concatinates
+ * the `header.scope`, `header.type` and `header.subject` properties.
+ *
+ * **Example**
+ *
+ * ```js
+ * import { parse } from 'parse-commit-message';
+ *
+ * const commit = parse(`fix(crit): some huge change
+ *
+ * Some awesome
+ * body here.
+ *
+ * resolves #333
+ * `);
+ *
+ * console.log(commit)
+ * // => {
+ * //   header: {
+ * //     type: 'fix',
+ * //     scope: 'crit',
+ * //     subject: 'some huge change'
+ * //     toString: [Function: toString],
+ * //   },
+ * //   body: 'Some awesome\nbody here.',
+ * //   footer: 'resolves #333',
+ * // }
+ *
+ * console.log(commit.header.toString())
+ * // => 'fix(crit): some huge change'
+ *
+ * // or adding one more plugin to the builtin ones
+ * const customPlugin = (commit) => {
+ *   if (commit.header.type === 'fix') {
+ *     return { fixed: 'yeah' };
+ *   }
+ *   return null;
+ * };
+ * const commit = parse('fix(wat): foo bar baz', plugins.concat(customPlugin));
+ *
+ * console.log(commit.isBreaking) // => false
+ * console.log(commit.increment) // => 'patch'
+ * console.log(commit.header); // => { type: 'fix', subject: 'wat', subject: 'foo bar baz' }
+ * console.log(commit.fixed); // => 'yeah'
+ * ```
+ *
+ * @name  .parse
+ * @param {string} `commitMessage` required, a whole commit message
+ * @param {Array} `plugins` optional, a list of functions that are passed with `commit` object
+ * @return {Object} with `{ header: { type, scope, subject }, body, footer }`
+ * @api public
  */
+
 function parse(commitMessage, plugins) {
   if (typeof commitMessage !== 'string') {
     throw new TypeError(
@@ -116,15 +174,79 @@ function mentionsMapper({ header, body, footer }) {
 
 /**
  * An object with all mappers, such as `plugins` array, but named.
+ * This objects is like `{ increment, mentions }` where they are plugins
+ * that can be passed as second argument to `.parse`.
+ *
+ * 1. The `mappers.increment` adds `isBreaking` and `increment` properties
+ * to the final returned "commit" object:
+ * - `isBreaking` is `Boolean` that indicates if commit is containing `BREAKING CHANGE: ` or
+ * the `type` of the commit is `break`, `breaking` or `major`
+ * - `increment` is a `String` that can be `'patch'`, `'minor'` or `'major'`
+ *
+ * 2. The `mappers.mentions` adds `mentions` property to the end result object
+ * - `mentions` is an array of objects like `{ handle: String, mention: String, index: Number }`,
+ * see [collect-mentions][]
+ *
+ * **Example**
+ *
+ * ```js
+ * import { parse, mappers } from 'parse-commit-message';
+ *
+ * const commit = parse('fix: BREAKING CHANGE: huge refactor', mappers.increment);
+ *
+ * console.log(commit);
+ * // => {
+ * //   header: { type: 'fix', scope: undefined, subject: 'BREAKING CHANGE: huge refactor' },
+ * //   body: null,
+ * //   footer: null,
+ * //   isBreaking: true,
+ * //   increment: 'major'
+ * // }
+ *
+ * const str = `feat(whoa): thanks to @foobie for this
+ *
+ * awesome @zazzy and @quxie make this release to happen
+ *
+ * resolves #123
+ * `
+ * const cmt = parse(str, mappers.mentions);
+ *
+ * console.log(cmt.header.type); // => 'feat'
+ * console.log(cmt.header.scope); // => 'whoa'
+ * console.log(cmt.header.subject); // => 'hanks to @foobie for this'
+ * console.log(cmt.body); // => 'awesome @zazzy and @quxie make this release to happen'
+ * console.log(cmt.footer); // => 'resolves #123'
+ * console.log(cmt.mentions[0]); // => { handle: '@foobie', mention: 'foobie' }
+ * console.log(cmt.mentions[1]); // => { handle: '@zazzy', mention: 'zazzy' }
+ * console.log(cmt.mentions[2]); // => { handle: '@quxie', mention: 'quxie' }
+ * ```
+ *
+ * @name .mappers
+ * @api public
  */
+
 const mappers = {
   increment: incrementMapper,
   mentions: mentionsMapper,
 };
 
 /**
- * A list of all plugins, such as `mappers` but no names.
+ * A list of all plugins, such as `mappers` but no names,
+ * so can be passed directly to the `.parse` as second argument.
+ *
+ * **Example**
+ *
+ * ```js
+ * import { parse, plugins } from 'parse-commit-message';
+ *
+ * const commit = parse('fix: okey', plugins)
+ * console.log(commit)
+ * ```
+ *
+ * @name .plugins
+ * @api public
  */
+
 const plugins = Object.keys(mappers).map((name) => mappers[name]);
 
 /**