node-comment-extractor

NodeJS module to extract comments from source files with a not regex-based parser.

Installation

You can install with npm:

npm install comment-extractor

Usage

var commentExtractor = require('comment-extractor');

// extracts comments from a source file
var commentList = commentExtractor.extractCommentsFromFile('/path/to/file.php');

// extracts comments from a source code
var commentList = commentExtractor.extractCommentsFromString('source code', {language: 'php'});

// extracts TODOs contained in comments
var todoList = commentExtractor.extractTodosFromComments(commentList);

API

extractCommentsFromFile(filePath [, options])

• filePath: String
• options: Object
  • identifier: a string used to help you to identify the source file (default: filePath).
  • language: force the language used to parse source file.
  • charset: specify the charset (default: utf8). Valid charsets are those used by the fs NodeJS module.
• Return: Comment[]

Extracts comments from a source file.

By default, the language is determined by the file extension.

extractCommentsFromString(sourceCode, options)

• sourceCode: String
• options: Object
  • identifier: a string used to help you to identify the source code (default: unknown).
  • language: specify the language used to parse source file. required
• Return: Comment[]

Extracts comments from a source code string.

extractTodosFromComments(commentList [, tagList])

• commentList: Comment[]
• tagList: string[]
• Return: Todo[]

Extracts TODOs from a comment list.

By default, TODO tags are : TODO, @TODO, @todo, FIXME. You can specify your own list of tags with the tagList parameter, which will override the default tag list.

Comment

• text: the comment text
• lineStart: start line of the comment in the source file.
• sourceIdentifier: a string used to help you to identify the source file in which the comment was extracted.

Todo

• text: the TODO text
• line: line of the TODO in the source file.
• sourceIdentifier: a string used to help you to identify the source file in which the TODO was extracted.

Examples

Retrieve comments from a PHP file

Source file:

<?php
/*
 * Comment text
 */

$string = '
    // is part of a string, so it is ignored
';

JS code:

var commentList = commentExtractor.extractCommentsFromFile('/path/to/source-file.php');
console.log(commentList);

Output:

[
    Comment {
        text: 'Comment text',
        lineStart: 3,
        sourceIdentifier: '/path/to/source-file.php'
    }
]

Retrieve TODOs from a PHP file

Source file:

<?php
/*
 * hidden text TODO todo text
 */

$string = '
    // TODO is part of a string, so it is ignored
';

JS code:

var commentList = commentExtractor.extractCommentsFromFile('/path/to/source-file.php');
var todoList    = commentExtractor.extractTodosFromComments(commentList);
console.log(todoList);

Output:

[
    Todo {
        text: 'todo text',
        line: 3,
        sourceIdentifier: '/path/to/source-file.php'
    }
]

Retrieve TODOs with custom tags

Source file:

<?php
/*
 * CUSTOM_TAG todo text
 * TODO this tag no longer works
 */

JS code:

var commentList = commentExtractor.extractCommentsFromFile('/path/to/source-file.php');
var todoList    = commentExtractor.extractTodosFromComments(commentList, ['CUSTOM_TAG']);
console.log(todoList);

Output:

[
    Todo {
        text: 'todo text',
        line: 3,
        sourceIdentifier: '/path/to/source-file.php'
    }
]

Supported languages

Currently, supported languages are : CSS, HTML, JavaScript, JSON, TypeScript, PHP, XML. More coming soon.

Any PR to add languages are welcome.

Author

This project is authored and maintained by Stephen Berquet.

License

Licensed under the MIT License - see the LICENSE file for details