doclinkts v0.0.1

doclinkts

A super light NodeJS CLI app to link and auto-copy doc comments within your code.

Install

npm i doclinkts -g for global installation or npm i doclinkts --save-dev as a local dev dependency.

Run

To run it in a specified directory, just start node doclinkts ./dir. The root directory can contain a docignore.json file (see Configuration).

How it Works

To enable doclinkts to link and copy your comments, you have to specify docroots and doctargets within your sourcode.

A root comment must always start with the docroot declaration and a unique key:

/**[docroot key]
 * comment text
 * */
const x = () => {}

A target comment must always contain the doctarget declaration on the line where the root should be copied to. The declaration has the options i and r. One of those options must be selected.

/**
 * [doctarget key][i|r]
 * additional comment text
 * */
const x = () => {}

If the i option is selected, the root text will be inserted in the target text (see Example 1). If the r option is selected, the root text will replace the target text (see Example 2).

Example 1

// src/abstract/validator.ts

/**
 * The Validator interface is the abstract representation to
 * do some validation.
 * This comment has no link or target, so it just stays in place.
 * */
interface Validator {

    /**[docroot validator#validate]
     * Validates the given property.
     * @param{data} the string property to validate
     * */
    validate: (data: string) => boolean

}

// src/email/emailvalidator.ts

/**
 * The EmailValidator class provides functionality to validate 
 * email format properties.
 * This comment has no link or target, so it just stays in place.
 * */
class EmailValidator implements Validator {

    /**
     * [doctarget validator#validate][i]
     * Returns true, if the given property is a valid email adress.
     * */
    public validate(data: string): boolean {
        //do some stuff here
        return true;
    }
}

If you now run doclinkts in your src directory, all targets receive their root value. The file emailvalidator.ts will now look like the following:

// src/email/emailvalidator.ts

/**
 * The EmailValidator class provides functionality to validate 
 * email format properties.
 * This comment has no link or target, so it just stays in place.
 * */
class EmailValidator implements Validator {

    /**
     * [doctarget validator#validate][i]
     * #from src/abstract/validator.ts
     * Validates the given property.
     * @param{data} the string property to validate
     * #
     * Returns true, if the given property is a valid email adress.
     * */
    public validate(data: string): boolean {
        //do some stuff here
        return true;
    }
}

Example 2

If in src/email/emailvalidator.ts the r option [doctarget validator#validate][r] would be used, the resultion file will look like the following:

// src/email/emailvalidator.ts

/**
 * The EmailValidator class provides functionality to validate 
 * email format properties.
 * This comment has no link or target, so it just stays in place.
 * */
class EmailValidator implements Validator {

    /**
     * [doctarget validator#validate][r]
     * Validates the given property.
     * @param{data} the string property to validate
     * */
    public validate(data: string): boolean {
        //do some stuff here
        return true;
    }
}

Configuration

A target directory can contain a docignore.json file. All rules will be applied to the current and all child directories.

A docignore.json can include JS regular expressions. If one of the expressions match on a file uri, the file or directory is ignored. Note, a directory path does not include the trailing /.

Example

{
  "ignore": [
    "\\.test\\.",
    "^(mock)(.*)\\.xml$"
  ]
}

In this example, all files which contains .test. are ignored and all XML files starting with mock are ignored.

Note: the ignore file does not support expression flags.