# cdocparser

> Extract C style comments and extract context from source

Latest version **0.15.0** (published 2018-01-09) · MIT license · 15.7K weekly downloads

## Install

```sh
npm install cdocparser
pnpm add cdocparser
yarn add cdocparser
bun add cdocparser
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.15.0 |
| Published | 2018-01-09 |
| First published | 2014-07-04 |
| Weekly downloads | 15.7K |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Fabrice Weinberg |
| Maintainers | pascalduez, hugogiraudel, valeriangalliat, fweinb |
| Keywords | doc, documentation, extract, parse |

## Links

- npm: https://www.npmjs.com/package/cdocparser
- Repository: https://github.com/FWeinb/CDocParser
- Homepage: https://github.com/FWeinb/CDocParser#readme
- Issues: https://github.com/FWeinb/CDocParser/issues
- npm.io page: https://npm.io/package/cdocparser

## Dependencies (4)

- [lodash.union](https://npm.io/package/lodash.union.md) ^3.1.0
- [strip-indent](https://npm.io/package/strip-indent.md) ^1.0.0
- [lodash.assign](https://npm.io/package/lodash.assign.md) ^2.4.1
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) ^1.0.2

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 0.15.0 (latest) — 2018-01-09
- 0.14.0 (beta) — 2015-06-06
- 0.13.0 — 2015-01-27
- 0.12.2 — 2015-01-21
- 0.12.1 — 2015-01-20
- 0.12.0 — 2015-01-19
- 0.11.2 — 2015-01-08
- 0.11.1 — 2014-12-31
- 0.11.0 — 2014-11-27
- 0.10.0 — 2014-11-23
- 0.9.1 — 2014-10-31
- 0.9.0 — 2014-10-18
- 0.8.1 — 2014-10-18
- 0.8.0 — 2014-10-17
- 0.7.0 — 2014-10-15
- … 37 more at https://npm.io/package/cdocparser/versions

## README

CDocParser
---
CDocParser is a language agnostic C and `///`-Style comments parser that uses block and line comments to make it easier to generate documentation.


## Install

```bash
$ npm install --save cdocparser
```


## Usage

CDocParser consists of two parts the `CommentExtractor` and a `CommentParser`.


```js
var CDocParser = require('cdocparser');
var extractor = new CDocParser.CommentExtractor(/* contextParser */ );
var parser = new CDocParser.CommentParser(/* Annotations */);

var comments = extractor.extract(/* code */);
var parsedComments = parser.parse(comments);

console.log(parsedComments);
```

## API

### CommentExtractor

The ComemntExtractor is used to extract C and `///`-Style comments from source and attach context information to it.

#### `new CommentExtractor(contextParser, [opts])`

Create a CommentExtractor to extract block comment like:

```
/**
 *
 *  CDocComment
 *
 */
```

You need to pass in a function that is used to generate a `context` object used to specify the context of the comment.
A context obj:

```js
{
  type : 'contextType'
}
```

The `type` attribute is mandatory, you can add as much attributes as you would like.

To support custom comment formats set `lineCommentStyle` and/or `blockCommentStyle` in the `opts` argument, shown here with default values:

```
new CommentExtractor(contextParser, {
  lineComment: true,
  blockComment: true,
  lineCommentStyle: '///',
  blockCommentStyle: '/**'
})
```

The default regex can be found in index.js (`var defaultDocCommentRegEx = ...`).

#### `#extract(code)`

This method will return an Array of all comments in the form of

```js
[
  {
    lines: [],
    type: 'block|line|poster',
    commentRange: { start : 1, end : 2 },
    context: [context object generated by contextParser]
  }
]
```


### CommentParser

#### `new CommentParser(annotations, config)`

Create a new `CommentParser` where `annotations` is an object like:
```js
{
  _: {
    alias: {
      'aliasName': 'aRealAnnotation'
    }
  },

  aRealAnnotation: {
    parse : function (annotationLine, info, id) {

    },
    default : function(){
      return 5;
    }
  }
}
```

This object is used to provide parser for various types of annotations. It also includes tha ability to include aliases.

#### `#parse ( comments [, id ])`

This methods takes a comments array provided by `CommentExtractor#extract` and parses all annotations. The resulting
object will look like:

```js
{
  "[context.type]" : [
    {
      description : "[Contains all comment lines without an annotation]",
      commentRange : { start : [start], end : [end] },
      [annotationName] : [resultOfAnnotationParser]
    }
  ]
}
```


### Annotations API

The annotations object is build up from two different kind of object. A `annotation` object and a
`alias`.

The global structure looks like:
```
{
  _ : {
    [alias object]
  },
  [annotation object],
  [annotation object]
}
```


### A `annotation` object

#### Overview
```js
name : {
  parse : function(line, info, id){

  },

  autofill : function(comment){

  },

  default : function(comment){

  },

  multiple : true,

  overwritePoster : true
}
```

Each annotation must have a `parse` method, optionally you can have a `default` and `extend` methods. The optional `multiple` key is used to indicate if an annotation can be used multiple times.

#### `parse` method
The `parse` method is used to parse the actual `string` after the `@name`. All values returned from that method
will be wrapped in an array.

##### Example:
Implementing a `name` annotation:

```js
/**
 * @name Fabrice Weinberg
 */
```

```js
function(line){
  return {
    name : line
  }
}
```

#### `default` method
The `default` method is used to add a default value.

##### Example:
```js
function(comment){
  return [{
    name : 'Default Name'
  }]
}
```
> Note: Please keep in mind that you need to wrap values in an Array to align with hand written annotations


#### `autofill` method
The `autofill` method is used to extend hand written annotations by autofilled ones.

##### Example:
```js
function(comment){
  // Access the parsed comment here.
}
```

> Note: Extended annotations can be disabled by using the `@allowExtend` annotation.


#### `multiple` key

The `multiple` key is used to determine if this can be used mutliple times per comment.

> Note: A warning will be emitted if a annotation is used more than once. Only the first value is used.

### `overwritePoster` key

The `overwritePoster` key is used to control if a this annotation used on an item will overwrite a poster comment.

## Development

Use `mocha test` to run the unit tests.

## Changelog

#### 0.15.0

  * Allow restricting `lineCommentStyle` match to the beginning of a line. (See [PR#17](https://github.com/FWeinb/CDocParser/pull/17))

#### 0.13.0

  * Fix a bug where only in `multiple:false` case meta-information where included in `annotation.parse`.
  * Include `id` passed to `parse` method in every `annotation.parse` call.

#### 0.12.2

  * Fix a bug where poster comments could be deteced inside strings.

#### 0.12.1

  * Unify platform specify line breaks (like `\r\n`) to `\n` before processing

#### 0.12.0

  * Add the options `lineComment` and `blockComment` as boolean states to disbale parsing of either of them.

#### 0.11.0

  * Add the ability to pass in a `id` string to the `parse` function. Used for error reporting.

#### 0.10.0

  * return a flat array of comments.
  * added `indexBy` and `indexByType` to restore the previous behaviour.

#### 0.9.1

  * Prevent negative indexes. (See [PR#10](https://github.com/FWeinb/CDocParser/pull/10))
  * Unify error messages.

#### 0.9.0

  * Include `commentRange` in object returned by the annotation parser.

#### 0.8.1

  * Fix regression in `lineNumberFor` reporting wrong line numbers.

#### 0.8.0

  * Add the ability to specify `lineCommentStyle` and `blockCommentStyle`. (See [PR#8](https://github.com/FWeinb/CDocParser/pull/8))

#### 0.7.0

  * Extend `type` key of each comment to differentiate between `line` and `block`.

#### 0.6.0

  * Include line numbers in each found comment block. (See [PR#6](https://github.com/FWeinb/CDocParser/pull/5))

#### 0.5.0

 * Add `multiple` key, to indicate if a annotation can be used more than once per comment.

#### 0.4.0

  * Add `autofill` as an annotation feature.
  * Remove the array wrapping of `default` values.

#### 0.3.8

  * Add type check for poster comments

#### 0.3.7

 * Fix broken API in `0.3.5` and `0.3.6`

#### 0.3.5

 * Use raw arrays returned from `default` as value.

#### 0.3.4

 * Pass in the parsed item to the `default` function

#### 0.3.3

 * Fix a bug with line comments that are indented

#### 0.3.2

 * Add `allowedOn` key to annotations to only apply them to comments from a specific type

#### 0.3.0

 * Add support for `///` comments
 * Add a `lineNumberFor` function as a second parameter that will convert char indices to line numbers

#### 0.2.2

  * Add a `poster comment` to apply annotations to all items in the file that are documented.
  * Emits a `warning` if you use more than on `poster comment` per file. Only the first one will be used.

#### 0.2.1

  * Emits a `warning` if a annotation was not found instead of throwing an exception.

#### 0.2.0

  * Throw an error if annotation was not found

#### 0.1.1

  * Ignore annotations that return `undefined`.

#### 0.1.0

  * Restructure annotation function. Add `default` value and `parse` function.

---
_Source: https://npm.io/package/cdocparser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._