javadoc

    2.0.0 • Public • Published

    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.

    Install

    npm i javadoc

    DownloadsWeekly Downloads

    29

    Version

    2.0.0

    License

    WTFPL

    Unpacked Size

    209 kB

    Total Files

    31

    Last publish

    Collaborators

    • avatar