CDocParser is a language agnostic C and ///
-Style comments parser that uses block and line comments to make it easier to generate documentation.
$ npm install --save cdocparser
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);
The ComemntExtractor is used to extract C and ///
-Style comments from source and attach context information to it.
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.
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 = ...
).
This method will return an Array of all comments in the form of
[
{
lines: [],
type: 'block|line|poster',
commentRange: { start : 1, end : 2 },
context: [context object generated by contextParser]
}
]
Create a new CommentParser
where annotations
is an object like:
{
_: {
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.
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]",
commentRange : { start : [start], end : [end] },
[annotationName] : [resultOfAnnotationParser]
}
]
}
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]
}
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.
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.
Implementing a name
annotation:
/**
* @name Fabrice Weinberg
*/
function(line){
return {
name : line
}
}
The default
method is used to add a default value.
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
The autofill
method is used to extend hand written annotations by autofilled ones.
function(comment){
// Access the parsed comment here.
}
Note: Extended annotations can be disabled by using the
@allowExtend
annotation.
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.
The overwritePoster
key is used to control if a this annotation used on an item will overwrite a poster comment.
Use mocha test
to run the unit tests.
- Fix a bug where only in
multiple:false
case meta-information where included inannotation.parse
. - Include
id
passed toparse
method in everyannotation.parse
call.
- Fix a bug where poster comments could be deteced inside strings.
- Unify platform specify line breaks (like
\r\n
) to\n
before processing
- Add the options
lineComment
andblockComment
as boolean states to disbale parsing of either of them.
- Add the ability to pass in a
id
string to theparse
function. Used for error reporting.
- return a flat array of comments.
- added
indexBy
andindexByType
to restore the previous behaviour.
- Prevent negative indexes. (See PR#10)
- Unify error messages.
- Include
commentRange
in object returned by the annotation parser.
- Fix regression in
lineNumberFor
reporting wrong line numbers.
- Add the ability to specify
lineCommentStyle
andblockCommentStyle
. (See PR#8)
- Extend
type
key of each comment to differentiate betweenline
andblock
.
- Include line numbers in each found comment block. (See PR#6)
- Add
multiple
key, to indicate if a annotation can be used more than once per comment.
- Add
autofill
as an annotation feature. - Remove the array wrapping of
default
values.
- Add type check for poster comments
- Fix broken API in
0.3.5
and0.3.6
- Use raw arrays returned from
default
as value.
- Pass in the parsed item to the
default
function
- Fix a bug with line comments that are indented
- Add
allowedOn
key to annotations to only apply them to comments from a specific type
- Add support for
///
comments - Add a
lineNumberFor
function as a second parameter that will convert char indices to line numbers
- Add a
poster comment
to apply annotations to all items in the file that are documented. - Emits a
warning
if you use more than onposter comment
per file. Only the first one will be used.
- Emits a
warning
if a annotation was not found instead of throwing an exception.
- Throw an error if annotation was not found
- Ignore annotations that return
undefined
.
- Restructure annotation function. Add
default
value andparse
function.