Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jonschlinkert/parse-comments
Parse JavaScript code comments. Works with block and line comments, and should work with CSS, LESS, SASS, or any language with the same comment formats.
https://github.com/jonschlinkert/parse-comments
apidoc babel catharsis code comments context docs doctrine documentation espree esprima javascript jonschlinkert jsdoc markdown nodejs parse
Last synced: 5 days ago
JSON representation
Parse JavaScript code comments. Works with block and line comments, and should work with CSS, LESS, SASS, or any language with the same comment formats.
- Host: GitHub
- URL: https://github.com/jonschlinkert/parse-comments
- Owner: jonschlinkert
- License: mit
- Created: 2014-08-09T20:32:46.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2022-12-19T13:58:08.000Z (almost 2 years ago)
- Last Synced: 2024-10-23T14:07:01.454Z (13 days ago)
- Topics: apidoc, babel, catharsis, code, comments, context, docs, doctrine, documentation, espree, esprima, javascript, jonschlinkert, jsdoc, markdown, nodejs, parse
- Language: JavaScript
- Homepage: https://github.com/jonschlinkert
- Size: 600 KB
- Stars: 67
- Watchers: 5
- Forks: 23
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: .github/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
# parse-comments [](https://www.npmjs.com/package/parse-comments) [](https://npmjs.org/package/parse-comments) [](https://npmjs.org/package/parse-comments) [](https://travis-ci.org/jonschlinkert/parse-comments)
> Parse code comments from JavaScript or any language that uses the same format.
Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
## Install
Install with [npm](https://www.npmjs.com/):
```sh
$ npm install --save parse-comments
```
## Usage
```js
const Comments = require('parse-comments');
const comments = new Comments();
const ast = comments.parse(str);
console.log(ast);
```
Parses a comment like this:
```js
/**
* Create an instance of `CustomClass` with the given `options`.
*
* @param {String} options
* @api public
*/
class CustomClass {
constructor(options) {
this.options = options;
}
set(type, fn) {
// do stuff
}
}
```
Into an array of comment objects, like this:
```js
[
{
type: 'BlockComment',
value: '\nCreate an instance of `CustomClass` with the given `options`.\n\n@param {String} options\n@api public',
range: [0, 117],
loc: { start: { line: 1, column: 0 }, end: { line: 6, column: 3 } },
codeStart: 119,
raw:
'*\n * Create an instance of `CustomClass` with the given `options`.\n *\n * @param {String} options\n * @api public\n ',
code: {
context: {
type: 'class',
ctor: 'CustomClass',
name: 'CustomClass',
extends: undefined,
string: 'new CustomClass()'
},
value: 'class CustomClass {',
range: [119, 138],
loc: { start: { line: 8, column: 0 }, end: { line: 8, column: 19 } }
},
description: 'Create an instance of `CustomClass` with the given `options`.',
footer: '',
examples: [],
tags: [
{
title: 'param',
name: 'options',
description: '',
type: { type: 'NameExpression', name: 'String' }
},
{ title: 'api', name: 'public', description: '' }
],
inlineTags: []
}
]
```
## API
### [Comments](index.js#L22)
Create an instance of `Comments` with the given `options`.
**Params**
* **{Object}**: options
**Example**
```js
const Comments = require('parse-comments');
const comments = new Comments();
```
Register a parser function of the given `type`
**Params**
* `type` **{string|object}**
* `fn` **{Function}**
* `returns` **{Object}**
**Params**
* `fn` **{Function}**: plugin function
* `returns` **{Object}**: Returns the comments instance for chaining.
**Example**
```js
// plugin example
function yourPlugin(options) {
return function(comments) {
// do stuff
};
}
// usage
comments.use(yourPlugin());
```
**Params**
* `type` **{String}**: The `node.type` to call the handler on. You can override built-in middleware by registering a handler of the same name, or register a handler for rendering a new type.
* `fn` **{Function}**: The handler function
* `returns` **{Object}**: Returns the instance for chaining.
**Example**
```js
comments.set('param', function(node) {
// do stuff to node
});
```
**Params**
* `type` **{String|Object|Array}**: Handler name(s), or an object of middleware
* `fn` **{Function}**: Handler function, if `type` is a string or array. Otherwise this argument is ignored.
* `returns` **{Object}**: Returns the instance for chaining.
**Example**
```js
comments.before('param', function(node) {
// do stuff to node
});
// or
comments.before(['param', 'returns'], function(node) {
// do stuff to node
});
// or
comments.before({
param: function(node) {
// do stuff to node
},
returns: function(node) {
// do stuff to node
}
});
```
**Params**
* `type` **{String|Object|Array}**: Handler name(s), or an object of middleware
* `fn` **{Function}**: Handler function, if `type` is a string or array. Otherwise this argument is ignored.
* `returns` **{Object}**: Returns the instance for chaining.
**Example**
```js
comments.after('param', function(node) {
// do stuff to node
});
// or
comments.after(['param', 'returns'], function(node) {
// do stuff to node
});
// or
comments.after({
param: function(node) {
// do stuff to node
},
returns: function(node) {
// do stuff to node
}
});
```
**Params**
* `javascript` **{String}**: String of javascript
* `options` **{Object}**
* `returns` **{Object}**: Returns an object with `description` string, array of `examples`, array of `tags` (strings), and a `footer` if descriptions are defined both before and after tags.
**Example**
```js
const parser = new ParseComments();
const tokens = parser.tokenize([string]);
```
**Params**
* `str` **{String}**: String of javascript
* `options` **{Object}**
* `returns` **{Array}**: Array of objects.
**Example**
```js
const parser = new ParseComments();
const comments = parser.parse(string);
```
**Params**
* `str` **{String}**: JavaScript comment
* `options` **{Object}**
* `returns` **{Object}**: Parsed comment object
**Example**
```js
let parser = new ParseComments();
let comments = parser.parseComment(string);
```
```js
**Params**
* **{}**: {String}
* **{String}**: name
* **{String}**: name The name to use for foo ```
* **{Object}**: tok Takes a token from
* `returns` **{Object}**
```js
**Params**
* **{}**: {String}
* **{String}**: name
* **{String}**: name The name to use for foo ```
* **{Object}**: tok
* `returns` **{Object}**
```js
**Params**
* **{}**: {String}
* **{}**: {...string}
* **{}**: {function(...a)}
* **{}**: {function(...a:b)}
* **{}**: {String|Array}
* **{}**: {(String|Array)}
* **{}**: {{foo: bar}}
* **{}**: {String[]}
* ``` **{Array=}**
* **{String}**: value The
* `returns` **{Object}**
```js
**Params**
* **{}**: {String}
* **{}**: {String|Array}
* **{}**: {(String|Array)}
* **{}**: {{foo: bar}} ```
* **{string}**: str The string to parse
* `returns` **{object}**
Returns true if the given `comment` is valid. By default, comments
are considered valid when they begin with `/**`, and do not contain
`jslint`, `jshint`, `eshint`, or `eslint`. A custom `isValid` function may be
passed on the constructor options.
**Params**
* `comment` **{Object}**
* `options` **{Object}**
* `returns` **{Boolean}**
## About
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](../../issues/new).
Please read the [contributing guide](.github/contributing.md) for advice on opening issues, pull requests, and coding standards.
Running Tests
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
```sh
$ npm install && npm test
```
Building docs
_(This project's readme.md is generated by [verb](https://github.com/verbose/verb-generate-readme), please don't edit the readme directly. Any changes to the readme must be made in the [.verb.md](.verb.md) readme template.)_
To generate the readme, run the following command:
```sh
$ npm install -g verbose/verb#dev verb-generate-readme && verb
```
### Contributors
| **Commits** | **Contributor** |
| --- | --- |
| 35 | [jonschlinkert](https://github.com/jonschlinkert) |
| 4 | [doowb](https://github.com/doowb) |
### Author
**Jon Schlinkert**
* [GitHub Profile](https://github.com/jonschlinkert)
* [Twitter Profile](https://twitter.com/jonschlinkert)
* [LinkedIn Profile](https://linkedin.com/in/jonschlinkert)
### License
Copyright © 2018, [Jon Schlinkert](https://github.com/jonschlinkert).
Released under the [MIT License](LICENSE).
***
_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on November 24, 2018._