readmongo/node_modules/comment-patterns/docs/contributing.md

Contributing

You can contribute by supplying new patterns for languages and by fixing errors in existing language definitions. This is especially true for the apidoc: true property, which marks a comment patterns to be used as apidoc-comment for the given language (see the c-style.js)

Small changes can be done in a pull-request without an issue.

If you think there is useful information that should be provided in the database, please create an issue before makeing a pull request. Since the database is precompiled and stored in a single file, there is always a trade-off between adding new features (fields) and keeping the file-size small.

Variations such as the .regex()-function are derived from core database and precompiled into a single file. If you think there should be another variation, please create an issue before submitting a pull-request.

Creating variations and indexes

Internally, the whole database is stored in two parts:

• The database itself is stored as commonjs-module in a javascript-file. It is essentially an array containing on entry for each language
• Indexes for the database are store in separated commonjs-modules (also in javascript-files). It allows quick access to the database by providing a javascript-object with the index-value as key and the database element-index as value.

The commentPatterns-method first looks for the given file-extension in the by-matcher.js index and then loads the appropriate entry from the database-array.

The database, its variations and indexes are created in the generate-db.js script which makes use of the Generator class.

In order to create a new index, you can do

var generator = new Generator();
generator.createIndex(indexFunction).writeTo(databaseDir, "by-name.js");

indexFunction must return a string or an array of string for an entry of the core-database. If the result is an array, every element is used as key for the entry.

In order to create a new variation, do

generator.transform(transformFunction).writeTo(databaseDir, "regexes.js");

transformFunction must return a new object for a given database-entry. The function is called like Array#map for each entry in the database.

Simple transform- and index-functions can be included in generate-db.js. More complex ones should be put in a separate file in the variations directory.

Updating the language-database

The language-specifications where initially pulled from the
language-database of groc.

Pulling updates from groc into the files in languages/patterns is not such a good idea anymore: Almost all files have been changed manually, so there would be a lot of conflicts to resolve. However, it is still possible, since the scripts are still there:

npm i -d && npm run-script update-from-groc

Be careful not to submit any regressions after updating the database.