javadoc

javadoc

Unopinionated, simple and powerful documentation generator.

Installation

$ npm i -g javadoc

Why?

This project was created to simplify the documentation of any code that accepts this kind of comments:

/**
 * 
 * Some description here. It accepts (optional) **markdown typing**.
 * 
 * @some-property Some value in *markdown*
 * @some-property Some value in *markdown*
 * @some-other-property Some value in *markdown*
 * @some-more-properties Some value in *markdown*
 * The continuation of the value.
 * It can take as much lines as you need.
 * @and-more-properties
 * @and-more
 * @and-more...
 * 
 */

Advantages

These are some of the advantages of this tool compared to other tools:

• Language unopinionated: it can be used in any programming language project, because:
  • It uses regular expressions.
  • It does not parse any source code.
• Glob patterns: it uses glob patterns to find files.
• Unlimited Javadoc-like tags: it uses the Javadoc styling but you are free to use any kind of tag, not only a limited set of them.
• JSON or Markdown output: it can extract Javadoc comments in:
  • JSON: to abstractly program the views of your own project.
  • Markdown: to directly use the comments in a typical README.md file, or similar.
• CLI or API: it has a command-line interface and an abstract programming interface, and both work almost the same way.

CLI usage

As simple as:

$ javadoc
  --include "**/*.js" "**/*.ts"
  --exclude "**/node_modules/**" "**ignore**"
  --format markdown
  --output README.md

Or abbreviatedly:

$ javadoc
  -i "**/*.php" "**/*.sql"
  -e "**/node_modules/**" "**ignore**"
  -f json
  -o README.md

Type javadoc --help to see the help.

API usage

require("javadoc").generate({
    include: ["**/*.js", "**/*.ts"],
    exclude: ["**/node_modules/**"],
    format: "markdown",
    output: "README.md"
}).then(report => {
    // manage a report of success and errors...
}).catch(error => {
    // manage the error...
});

API reference

Here you will find the whole API available for programmatic usage, documented.

Note: the main interesting method is Javadoc.generate, which is the one called by the CLI.

Javadoc

Type: Class. Function.

Description: Master class of the javadoc package.

Javadoc.REGEX_PATTERNS

Type: Static property. Object.

Description: Regular expression patterns used by the class.

Javadoc.DEFAULT_GLOB_OPTIONS

Type: Static property. Object.

Property:

• cwd. Defaults to process.cwd(). Allowed options at glob package

• dot. Defaults to true. Allowed options at glob package

Description: Default options used by the glob package.

Javadoc.DEFAULT_OPTIONS

Type: Static property. Object.

Property:

• include:Array<String>. Defaults to ["**/*.js"]. Allowed rules at glob package.

• exclude:Array<String>. Defaults to ["**/node_modules/**.js"]. Allowed rules at glob package.

• format:String. Defaults to "markdown". Allowed values:

  • "md"
  • "json"

• output:String. Defaults to undefined. File into which dump the results. Required value.

Description: General options of the Javadoc.generate main method.

Javadoc.findFiles

Type: Static method. Function.

Parameter:

• parameterIncludes:Array<String>. Replaces DEFAULT_OPTIONS.include as value.

• parameterExcludes:Array<String>. Replaces DEFAULT_OPTIONS.exclude as value.

• parameterOptions:Object. Overrides DEFAULT_GLOB_OPTIONS as object.

Returns: files:Promise<Array>. Asynchronously, returns an array of matched files (as Strings).

Description: Finds files based on glob patterns (more info) included, excluded and glob options (more info).

Javadoc.findCommentsInFile

Type: Static method. Function.

Parameter: file:String. File into which look for the javadoc-comments.

Returns: matches:Promise<Array<Object>>. Asynchronously, returns a list of matched javadoc-comments (as Objects) found in the passed file.

Description: From a file, it returns (asynchronously, by a Promise) javadoc-comments represented as Objects.

Javadoc.findCommentsInString

Type: Static method. Function.

Parameter: text:String. Text into which look for the javadoc-comments.

Returns: totalMatches:Array<Object>. List of javadoc-comments (as Objects) found in the passed String.

Description: Finds javadoc-comments (as Objects) from a String.

Javadoc.formatJsonToMarkdown

Type: Static method. Function.

Parameter: fileComments:Array<Object>. List of javadoc-comments (as Object) to convert to markdown format.

Returns: formatted:String. Markdown code from passed javadoc-comments.

Description: Generates markdown code from a list of javadoc-comments.

Javadoc.generate

Type: Static method. Function.

Parameter: parameters:Object. Overrides Javadoc.DEFAULT_OPTIONS as Object. To see more about properties, go to that static property of Javadoc class.

Returns: output:Promise<String|Array<Object>>. Depending on parameters.format ("json"|"markdown"), it can return an Array or a String.

Description: Finds included files, dismisses excluded files, extracts javadoc-comments, formats them adecuately, and dumps the results into output file, while returning the output asynchronously (as a Promise).

Tests

To run the test, clone the repository and run npm run test.

Coverage

To run the coverage test, clone the repository and run npm run cover.

License

This project is licensed under WTFPL, which stands for Do What The Fuck You Want To Public License.

Versioning

This project adheres to semantic versioning 2.0.

Issues

To communicate issues here.