Skip to content

Latest commit

 

History

History
111 lines (76 loc) · 3.65 KB

.verb.md

File metadata and controls

111 lines (76 loc) · 3.65 KB
Raw

{%= name %}

{%= description %}

This module contains an extract of the language-database of groc with information about how single- and multi-line comments are written in different languages.

Basic usage

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):

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.

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

Contributing

See the contributing guide

Run tests

{%= include("tests") %}

Related

{%= related(['extract-comments']) %}

Author

{%= include("author", {github: 'nknapp', twitter: 'knappi79'}) %}

License

{%= license() %}