@mangar2/js2md v0.2.1

Abstract

This module provides a parser and a generator to parse JSDOC tags in JavaScript files and generates a markdown based on a user-defined template . It scans the provided directory and generates one markdown file for all . js files in this directory

Example

// jsmddoc directory outputfile --json jsonFile --template templateFile
jsmddoc . README.md --json writeJSONFormatHere --template useMyOwnTemplate

Installation

Global installation

npm i @mangar2/js2md -g

Local installation

npm i @mangar2/js2md

Command line Parameters

jsmdoc directory outputFile [--json jsonFile] [--template templateFile]

directory

The directory to be scanned for JavaScript files. Only .js files are scanned.

outputFile

The name of the markdown file to create. Caution: it will overwrite existing files.

jsonFile

The name of the JSON file to create. js2md first creates a JSON tree and then generates a markdown from the JSON format. This option allows you to write the JSON data to a file. Caution it will overwrite existing files.

templateFile

You can create you own template file and thus fully control the output generation. The name of the generator template. The default file "template.json" will be used if no template file is specified.

Functionality

You get a prerelease version if you use it now. It works very well for my code, but the support of jsdoc commands is limited. If you miss a certain funtionality, please add a minimal JavaScript sniplet to the feature request. The following line is an example of a minimal JavaScript sniplet demonstrating the functionality to support arrow-notation functions with auto-detection of its name without the need of a @name tag.

/** @description function description */ const myfunction = () => { } /** function 2 */ const function2 = () => { }

My code usually consists of classes ("class") and global functions. This works well. Old style JavaScript code with functions, inner functions etc. is much less supported. Here is a rough list of features:

• Classes with documentation in front of the class definition, class name is usually "auto-detected" even after a module.exports ...
• Members in classes (use @type to document the type of getter/setter)
• Methods in classes
• Method an Function attributes (like async, const, ...)
• Parameters with name type and documentation including attributes like optional, default values, ... (hope I have at least jsdoc functionality here)
• Return values with type and documentation
• Global functions, functions declared as classes (with @class)
• File documenation (if the file has a @file, @fileoverview or @overview tag)
• Examples (File example is a script, class/function example is a JavaScript)
• Readonly (use the @readonly flag to exclude a file/class/function/method)
• @typedef to define types
• @callback to define callbacks
• @author, @licence, @documentation, @copywrit on file level (depends on the template)

Building your own template

Feel free to copy the existing template and change it to see what happens. The template is a JSON file. There is no check for template validity (I should add a JSON schema validator some time ...)

The main structure

{
    "templates": [
    ],
    "$def": {
    }

The templates (section "templates") are processed one after the other. Each template can use the full scan-result. Use the $defs part to define templates. Use them where ever you like in the templates or in the template definitions.

Generate a JSON output of your code and check the stucture, if you like to build your own template. The template definition must match the JSON structure to be effective.

You need to learn only a small amount of command to create your own template:

text

{
    "templates": [
        {"text": "This text will be copied to the markdown file" },
        {"text": "Use \n for line breaks" }
        {"text": "Feel free to use markdown elements like **bold** or #headline" },
        {"text": "Add @variable (like @name, ...) to include a variable content from the scan result" }
    ],
    "$def": {
    }

iterate on / for each

Use iterate on to iterate on an array. The following elements are iterable

• file
• class
  • member
    • param
    • returns
    • throws
  • method
  • typefef
  • callback
• function
• typedef
• callback

The content of the jsdoc tags are available and can be included by adding the tag in the generation text. Iterable elements usually have a "name" attribute. Use @name to get the names of classe, functions, methods, ...

Example: List all Class names

{
    "templates": [
        {"iterate on": "class", "for each": [
            { "text": "- @name\n" }
        ] }
    ],
    "$def": {
    }

This iterates on the array of classes and for each array creates a list entry with the class name.

if exists

Use if exists to generate text conditionally if an attibute exists. Attributes are mostly the same as the jsdoc tags (like @author, but skip the '@')

{
    "templates": [
        {"iterate on": "file", "for each": [
            { "- **File name** @filename; filename is always here\n" },
            { "if exists": "author", "text": "- **Author** @author\n" },
            { "if exists": "copyright", "text": "- **Copyright** @copyright\n" }
        ] }
    ],
    "$def": {
    }

if first

Use if first to do something on the first loop - for example place a headline.

{
    "templates": [
        {"iterate on": "file", "for each": [
            { "if first": true, "text": "## Files" }
            { "- **File name** @filename; filename is always here\n" },
            { "if exists": "author", "text": "- **Author** @author\n" },
            { "if exists": "copyright", "text": "- **Copyright** @copyright\n" }
        ] }
    ],
    "$def": {
    }

$ref

use $ref to structure your template

{
    "templates": [
        { "$ref": "file content" }
    ],
    "$def": {
        "file content": [
            {"iterate on": "file", "for each": [
                { "if first": true, "text": "## Files" }
                { "- **File name** @filename; filename is always here\n" },
                { "if exists": "author", "text": "- **Author** @author\n" },
                { "if exists": "copyright", "text": "- **Copyright** @copyright\n" }
            ] }
        ]
    }