Package Exports

extract-comments

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (extract-comments) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

extract-comments

Extract code comments from string or from a glob of files.

Heads up! As of v0.7.0 this no longer has a .fromFile() method to read from the file system. See [extracting from files].

Can be used with code-context to match comments up with related code.

Install with npm

npm i extract-comments --save

Usage

var extract = require('extract-comments');

// pass a string of javascript, CSS, LESS etc
extract(string);

Example

var str = '/**\n * this is\n *\n * a comment\n*/\nvar foo = "bar";\n';
extract(str);

Results in:

// key is the starting line number
{ '1':
   { begin: 1,
     end: 5,
     // line number of the code after the comment
     codeStart: 7 } }
     content: 'this is\n\na comment\n',
     // sames as content, but split into blocks at double newlines
     blocks: [
       'this is',
       'a comment\n'
     ],
     // first line of code after the comment
     after: 'var foo = "bar";',

(The reason the key is the starting line number is that it's easy to use this format with templates)

Customize output

// use code-context to parse the first line of code following
// the comment
var context = require('code-context');

// pass a function to modify the returned object
// and avoid looping more than once
var comments = extract(str, function(comment) {
  comment.context = context(comment.after);
  return comment;
});

Results in:

{ begin: 1,
  content: 'this is\n\na comment\n',
  after: 'var foo = "bar";',
  end: 5,
  codeStart: 7,
  blocks: [ 'this is', 'a comment\n' ],
  context:
   [ { begin: 1,
       type: 'declaration',
       name: 'foo',
       value: '"bar"',
       string: 'foo',
       original: 'var foo = "bar";' } ] }

Extracting from files

Prior to v0.7.0, there was a method to extract code comments from files. Here is the equivalent code to accomplish the same thing:

var fs = require('fs');
var extract = require('extract-comments');
var mapFiles = require('map-files');

function extractComments(patterns, opts) {
  opts = opts || {};
  opts.name = opts.rename || function(fp) {
    return fp;
  };
  opts.read = opts.read || function(fp, options) {
    var code = fs.readFileSync(fp, 'utf8');
    return extract(code, options);
  };
  return mapFiles(patterns, opts);
}

parse-comments: Parse code comments from JavaScript or any language that uses the same format.
code-context: Parse a string of javascript to determine the context for functions, variables and comments based on the code that follows.
esprima-extract-comments: Extract code comments from string or from a glob of files using esprima.

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue

Run tests

Install dev dependencies.

npm i -d && npm test

Author

Jon Schlinkert

License

This file was generated by verb-cli on March 12, 2015.