dok

jsdoc(file)

Generate docs JSON by using patched JSDoc haruki template. The patched version includes lineno.

• file String - JavaScript file with comments to parse

Returns

• Object - JSON data for all comments in file

parseArgs(fn)

Generate a String with comma separated function arguments. Put square brackets around optional arguments. Ignore child arguments like config.key.

• fn Object - JSON object for single function from JSDoc

Returns

• String - Comma separated arguments

Example

var fn = {
  name: 'sum',
  description: '...',
  parameters: [
    {
      name: 'x',
      optional: ''
    },
    {
      name: 'y',
      optional: true
    }
  ]
};
var out = parseArgs(fn);
// x, [y]

parseDescription(desc)

Generate gfm description from JSDoc description. Replace code tags with markdown code tags.

• desc String - JSDoc description string

Returns

• String - Markdown description

Example

var desc = '<p>Some description with variable <code>a</code></p>'
var parsed = parseDescription(desc);
// Some description with variable `a`

parseExamples(examples)

Generate gfm compatible code block from JSDoc parsed examples array.

• examples Array - JSDoc examples array

Returns

• Array - Fenced code blocks with separate caption

Example

var examples = [
  'var z = sum(10, 20);\nconsole.log(z);\n// 40'
];
var parsed = parseExamples(examples);
// [
//   '```javascript\nvar z = sum(10, 20);\nconsole.log(z);\n// 40\n```'
// ]

parseParams(params)

Generate markdown list item from parameter object.

• params Array - Array with parameters from JSDoc

Returns

• Array - Array with markdown list items

Example

var params = [
  {
    name: 'x',
    type: 'Number',
    description: '<p>First number</p>'
  },
  {
    name: 'y',
    type: 'Number',
    description: '<p>Second number</p>',
    default: '20',
    optional: true
  }
];
var parsed = parseParams(params);
// [
//   - `x` **Number** - First number
//   - `y` **Number** *optional*  - Second number - default `20`
// ]

parseReturns(returns)

Generate markdown returns block.

• returns Object - Returns object from JSDoc

Returns

• String - Markdown formatted list item

Example

var returns = {
  type: 'String',
  description: '<p>Some description here</p>'
};
var parsed = parseReturns(returns);
// - **String** - Some description here

render(fns)

Use handlebars to render template to index.html. Include line number for link to source code on GitHub.

• fns Array - Array with all functions from JSDoc json

clean()

Remove docs/ folder.

copy()

Copy CSS and JS folder to modules docs/ folder. These static assets are required for index.html.

write()

Write markdown files for each function.

create(file)

Create docs/ directory with .md partials in includes/ directory. Render index.html and copy statis assets (CSS and JS) to /docs directory.

• file String - JavaScript with JSDoc comments

getLevel(str)

Return heading level. Count number of hashes (#) in str.

• str String - Markdown heading string

Returns

• Number - Number of hashes

Example

var one = '## a';
var levelOne = getLevel(one);  // 2
var two = '#### b';
var levelTwo = getLevel(two);  // 4

index(section, headings)

Find section index in array with all README.md headings.

• section String - Section name

• headings Array - Array with all README.md headings

Example

var section = 'c';
var headings = ['# a', '## b', '## c', '## d', '## e'];
// 2

find(level, headings)

Find first heading with given level in headings array. headings is a subarray sliced just behind the heading after that we'd like to include the markdown content.

• level Number - Heading level. Number between 1 and 6

• headings Array - Partial array of all README.md headings

Example

var level = 3;
var headings = ['# a', '### b', '## c', '## d'];
var index = find(level, headings);
// 1

clear(section, readme)

Clear old content from readme. Start just behind section and look for next heading that has the same level. Everything in between is cleared.

• section String - Clear all content below this section

• readme String - All markdown content from README.md

Returns

• String - readme without any content below section

Example

README.md

# Some title

## Installation

`npm install module`

## Config

Here is how to configure the module.

### Sub config

...

## Methods

### sum(x,y)

Returns the sum of two Numbers.

...

## Test

...

## License

...

index.js

var readme = fs.readFileSync('./README.md', 'utf8');
var section = 'Methods';
readme = clear(section, readme);
// # Some title
//
// ## Installation
//
// `npm install module`
//
// ## Config
//
// Here is how to configure the module.
//
// ### Sub config
//
// ...
//
// ## Methods
//
// ## Test
//
// ...
//
// ## License
//
// ...

include(section, readme, content)

Include markdown content into readme.

• section String - content is included just below this section

• readme String - Old README.md that is cleared below section

• content content - The content to include after section

updateReadme(section)

Include .md partials in README.md below section.

• section String - Section name