mdextract/API.md

Extracts `/** code comments */` from code files and turns them into markdown docs. Supports JavaScript-style comments (other languages to come).

<!-- include: index.js -->

## mdextract
> `mdextract(src, options)`

Extracts source documents.

```js
var mdextract = require('mdextract');
var doc = mdextract(source);

console.log(doc.toMarkdown());
```

Returns a [Document] instance.

## Document
> `new Document(options)`

A document represents a bunch of source code.
A [mdextract] call will return a *Document* instance.

```js
var mdextract = require('mdextract');
var doc = mdextract(source);
```

Options available:

* `forceHeadings` *(boolean)* <span class='dash'>&mdash;</span> If true, sections without headings will be
  ignored.
* `lang` *(string)* <span class='dash'>&mdash;</span> Language to be used. Defaults to `"js"`.

When invoking mdextract from the command line with a `--json` option, the
result is a JSONified Document instance.

### options

The available options as received through the [Document] constructor.
Example:

```js
doc = mdextract(source);

doc.options
=> { lang: "js" }
```

### blocks

The list of section blocks as parsed away from the source. This is an
array of [Block] instances.

```js
doc = mdextract(source);

doc.blocks
=> [
  { internal: false,
    docline: 55,
    codeline: 66,
    level: 3,
    heading: "A heading",
    body: "This is the body in *markdown* format." },
  { ... },
  ...
]
```

### toMarkdown
> `.toMarkdown(options)`

Converts the document to markdown. Returns the Markdown string.

```js
doc = mdextract(source);
console.log(doc.toMarkdown());
=> "## heading\nthis is stuff extracted from your source.\n..."
```

Available options are:

* `showInternal` *(boolean)* <span class='dash'>&mdash;</span> renders internal/private API if true.

## Block

A section block. Options:

* `docline` *(number)* <span class='dash'>&mdash;</span> line number where the documentation starts
* `codeline` *(number)* <span class='dash'>&mdash;</span> line number where code starts
* `level` *(number)* <span class='dash'>&mdash;</span> heading level
* `heading` *(string)* <span class='dash'>&mdash;</span> heading text
* `subheading` *(string, optional)* <span class='dash'>&mdash;</span> optional subheading text
* `body` *(string)* <span class='dash'>&mdash;</span> body text

<!-- /include: index.js -->

[mdextract]: #mdextract
[Document]: #document
[Block]: #block