You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
112 lines
3.6 KiB
112 lines
3.6 KiB
4 years ago
|
# {%= name %}
|
||
|
|
|
||
|
|
> {%= description %}
|
||
|
|
|
||
|
|
This module contains an extract of the [language-database of `groc`](http://nevir.github.io/groc/languages.html)
|
||
|
|
with information about how single- and multi-line comments are written in different languages.
|
||
|
|
|
||
|
|
## Basic usage
|
||
|
|
|
||
|
|
```js
|
||
|
|
var commentPattern = require('{%= name %}');
|
||
|
|
var p = commentPattern('filename.js');
|
||
|
|
```
|
||
|
|
This will lead to `p` being:
|
||
|
|
|
||
|
|
{%= commentPatterns('filename.js') %}
|
||
|
|
|
||
|
|
* **name** is the name of the language
|
||
|
|
* **nameMatchers** is an array of file extensions of filenames that
|
||
|
|
files in this language usually have.
|
||
|
|
* **multiLineComment** is an array of patterns for comments that may span multiple lines
|
||
|
|
* **start** is the beginning of a comment
|
||
|
|
* **middle** is a character of a regex that occurs in front of each comment line
|
||
|
|
* **end** marks the end of the comment
|
||
|
|
* **singleLineComment** is the prefix of comments that go until the end of the line
|
||
|
|
|
||
|
|
## Variation (regex)
|
||
|
|
|
||
|
|
It is also possible to retrieve a regular expression that matches comments
|
||
|
|
(up to the next line of code):
|
||
|
|
|
||
|
|
```js
|
||
|
|
var re = commentPattern.regex('filename.js');
|
||
|
|
```
|
||
|
|
The result `re` will be:
|
||
|
|
|
||
|
|
{%= commentPatterns_regex('filename.js') %}
|
||
|
|
|
||
|
|
* **regex** is the actual regular expression. It matches the comments in a string,
|
||
|
|
including any empty lines after the comment.
|
||
|
|
* **cg** are constant values refering to capturing groups of the regex.
|
||
|
|
* `match[cg.indent]` contains the spaces that indent comment-start-delimiter.
|
||
|
|
* `match[cg.wholeComment]` matches the comment including delimiters.
|
||
|
|
* `match[cg.contentStart]` is the first group that captures the contents of the comment
|
||
|
|
In this case, there are multiple possible delimiters, so dependending on which
|
||
|
|
delimiter is used, `match[cg.contentStart]` or `match[cg.contentStart + 1]` is
|
||
|
|
filled. the others are undefined.
|
||
|
|
* **middle** contains one pattern for each group after `cg.contentStart` that matches
|
||
|
|
the prefix used before comment lines. It can be used to remove this prefix.
|
||
|
|
If the middle-prefix for this capturing group is empty (`''`), the pattern is `null`.
|
||
|
|
* **info** contains additional information for each group after `cg.contentStart`, currently
|
||
|
|
this information is only `{ apidocs: true }` if the group is matching an apidoc comment.
|
||
|
|
* **name** is the language name for debugging purposes.
|
||
|
|
|
||
|
|
## Variation (codeContext)
|
||
|
|
|
||
|
|
For API-documentation, it is important to determine the context of the comment (i.e.
|
||
|
|
the thing that the comment is documenting). Although this does not strictly belong to
|
||
|
|
the comment itself, this library also has methods to determine the code-context of a comment
|
||
|
|
These are functions that return a json by matching a single-line of code against a regular expression.
|
||
|
|
|
||
|
|
```js
|
||
|
|
var detector = commentPattern.codeContext("filename.js");
|
||
|
|
var cc = detector("function abc(param1,param2) {",2);
|
||
|
|
```
|
||
|
|
|
||
|
|
The result in `cc` will be
|
||
|
|
|
||
|
|
{%= codeContext("filename.js","function abc(param1,param2) {",2) %}
|
||
|
|
|
||
|
|
|
||
|
|
This result (for 'JavaScript' is actuall taken from the `parse-code-context` module by Jon Schlinkert.
|
||
|
|
The method `codeContext` returns a `Detector`
|
||
|
|
|
||
|
|
## API-Reference
|
||
|
|
|
||
|
|
{%= apidocs("index.js") %}
|
||
|
|
|
||
|
|
### The code-context detector
|
||
|
|
|
||
|
|
{%= apidocs("lib/detector.js") %}
|
||
|
|
|
||
|
|
## The database
|
||
|
|
|
||
|
|
The language-specification can be found in the
|
||
|
|
`languages`-directory. There is one file
|
||
|
|
for each language. The actual databases will be
|
||
|
|
created from these files on `prepublish`.
|
||
|
|
|
||
|
|
[The content of language database can be found here](docs/languages.md)
|
||
|
|
|
||
|
|
## Contributing
|
||
|
|
|
||
|
|
See the [contributing guide](docs/contributing.md)
|
||
|
|
|
||
|
|
## Run tests
|
||
|
|
|
||
|
|
{%= include("tests") %}
|
||
|
|
|
||
|
|
## Related
|
||
|
|
{%= related(['extract-comments']) %}
|
||
|
|
|
||
|
|
## Author
|
||
|
|
{%= include("author", {github: 'nknapp', twitter: 'knappi79'}) %}
|
||
|
|
|
||
|
|
## License
|
||
|
|
{%= license() %}
|
||
|
|
|
||
|
|
***
|
||
|
|
|
||
|
|
|