cdocparser

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

$ npm install --save cdocparser

Usage

CDocParser consists of two parts the CommentExtractor and a CommentParser.

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)

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:

{
  type : 'contextType'
}

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

#extract(code)

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

[
  {
    lines: {}, 
    context: [context object generated by contextParser]
  }
]

CommentParser

new CommentParser(annotations)

Create a new CommentParser where annotaions is an object like:

{
  _: {
    alias: {
      'aliasName': 'aRealAnnotation'
    }
  },

  aRealAnnotation: {
    parse : function (annotationLine) {
    
    },
    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 )

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

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

Development

Use mocha test to run the unit tests.

Changelog

0.3.0

• Add support for /// comments
• Add a lineNumber 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.