comment-to-doc

Comment-to-doc

Module for parsing specific type of comments and generating documentation from them. Comments are similar to ones used in jsdoc. This module parses comments and lets you define how you render them into a document and type of document. By default the output is a .md file (can be anything) and some default comment types are defined.

Why

Because I needed to generate some documentation from my code, but outputs of other modules were not what I needed. Some of them created HTML documentation webpages, others generated undesired markup. I wanted specifically to create .md files for each file that I had documented. This module is though able to generate files with any extension and output defined by user.

Install

npm install --save-dev comment-to-doc

Usage

The fastest way to get started with default configuration is like this:

import generateDocs, { Config, defaultTags } from "comment-to-doc";

const config: Config = {
  files: [
    './src/**/*.tsx',
  ],
  tags: defaultTags,
};

generateDocs(config);

Configuration

config

{
  files: string | string[],
  excludeFiles?: string | string[],
  tags?: Tag[],
  outputExt?: string,
  output?: (dir: string, fileName: string) => string,
  template?: Template,
  strict?: boolean,
  tagsOrder?: string[],
  tagsOrderInFiles?: {
    [fileNameOrPath: string]: string[]
  }
}

key	Mandatory	type	default	description
files	Mandatory	string or string[]	undefined	paths to files to read comments from (uses glob).
excludeFiles	Optional	string or string[]	undefined	paths to files which should be excluded from files paths (uses glob).
tags	Optional	Tag[]	[]	Tags configuration which define how each comment tag is rendered into documentation block. By default, if no tags are passed, only the tag with its content will be written to documentation file.
outputExt	Optional	string	md	Extension of output documentation file.
output	Optional	(dir: string, fileName: string) => string	${dir}/${fileName}.${outputExt}	Output path for documentation. Read file directory and name can be used to generate one.
template	Optional	Template	{ rules: {}, strictness: undefined, errorHandling: 'error' }	Configuration for enforcing specific tags and their order.
strict	Optional	boolean	false	If true, will only generate document with tags that are defined in "tags" array. By default all tags are used.
tagsOrder	Optional	string[]	undefined	You can specify the order of tags that will be written in document file. Useful when multiple files are concatted into single documentation file.
tagsOrderInFiles	Optional	{ [fileNameOrPath: string]: string[] }	undefined	You can specify the order of tags that will be written in document file per file. Overrides general order specified in tagsOrder for given file.

config.tags

A simple tag is defined like this:

type Tag = {
  tag: string,
  render?: (parsedComment: ParsedComment) => string,
  children?: Tag[]
}

For more details, click here to see how to configure tag in order to generate documentation.

config.template

• strictness TemplateStrictness.Strict | TemplateStrictness.IgnoreOrder
  • TemplateStrictness.Strict - Fail validation if any mandatory tag that does not exist in "template.rules" array is found or order of mandatory tags is not correct.
  • TemplateStrictness.IgnoreOrder - Fail validation if any mandatory tag that does not exist in "template.rules" array is found. Order is not important.
• rules { tag: string, mandatory?: boolean }
  • tag - the tag name which is also specified in tags array.
  • mandatory - set true if validation must apply to it.
• errorHandling ErrorHandling.Error | ErrorHandling.Warn
  • ErrorHandling.Error - Validation fails with an error and stops the process.
  • ErrorHandling.Warn - Validation fails with warnings and does not stop the process.

Comment syntax

Following example is the full syntax of the comment.

/**
 * @MyTagName:alias {type} [my,extra,data] my description
 * my content
 */

However, the only mandatory part of it is @MyTagName, so it can be as simple as this:

/**
 * @MyTag
 */

Multiple tags can alsoe exist in the same comment:

/**
 * @Tag
 */

/**
 * @MyTag
 * @MyOtherTag
 * @YetAnotherOne
 */

Valid comment styles are:

/**
 * @Tag:alias {type} [my,extra,data] my description
 * Content
 */

/** @Tag:alias {type} [my,extra,data] my description
Content
*/

/*
 * @Tag:alias {type} [my,extra,data] my description
 * Content
 */

/** @Tag:alias {type} [my,extra,data] my description */

/* @Tag:alias {type} [ my , extra, data] my description */

Note: Some of them do not support content

Note: Yes you can use spaces inside { type } and [ my , extra, data]

Parser

Following text

...

My code or whatever else stuff

/**
 * @MyTagName:alias {type} [my,extra,data] my description
 * my content
 */

My code or whatever else stuff

/**
 * @EmptyTag
 */

My code or whatever else stuff

/**
 * @EmptyTag {mytype!}
 */

My code or whatever else stuff

...

will be parsed into docsJSON which is following:

[
  {
    "tag": "MyTagName",
    "alias": "alias",
    "type": "type",
    "required": false,
    "extras": [
      "my",
      "extra",
      "data"
    ],
    "description": "my description",
    "content": "my content"
  },
  {
    "tag": "EmptyTag",
    "alias": "",
    "type": "",
    "required": false,
    "extras": [],
    "description": "",
    "content": ""
  },
    {
    "tag": "EmptyTag",
    "alias": "",
    "type": "mytype",
    "required": true,
    "extras": [],
    "description": "",
    "content": ""
  }
]

• tag - the name of the tag.
• alias - is used to connect parent with children, but can be used for whatever other reasons as well if children functionality not used.
• type - usually used to define a type (for example object type), but can be used for whatever other reasons.
• required - defines whether target is required. This is set to true if type value ends with ! mark.
• extras - possibility to pass extra data in order to help render doc from the tag.
• description - one-line description text.
• content - multi-line description text.

If you need to use the parser for your own purposes, you can import and use it like this:

import { commentParser } from "comment-to-doc";

commentParser(text, tags);

Generating document

The tag type is following:

type Tag = {
  tag: string,
  render?: (parsedComment: ParsedComment) => string,
  children?: Tag[]
}

1. Suppose we have a file called file.ts on root level with following comment:

   /**
    * @MyTagName {Singer} [Eminem, Marshall Mathers] He makes good music
    * Eminem said once:
    * > The truth is you don't know what is going to happen tomorrow. Life is a crazy ride, and nothing is guaranteed. I am whatever you say I am; if I wasn't, then why would you say I am.
    *
    * @Image [https://upload.wikimedia.org/wikipedia/commons/4/46/Eminem.png, Eminem] Image
    */
   

2. To define a single tag, give it a name and define how to render it into documentation block.

   const tag = {
     tag: 'MyTagName',
     render: ({tag, type, extras, description, content}) => {
       return [
         `## ${extras[0]}`,
         `- Name: ${extras[1]}`,
         `- He is ${type}`,
         `- ${description}`,
         '',
         content,
         '',
         `- created by ${tag}`
       ].join('\n');
     }
   }
   

3. Specify configuration

   const config = {
     files: [
       'example.ts',
     ],
     tags: [tag]  
   };
   

4. Run generator

   generateDocs(config);
   

5. This will be the output: example.md

CLI

Usage: comment-to-doc [options]

Options:
  -c, --config <path>  Path to configuration file.
  -i, --info           Include more info about generation results.
  -h, --help           display help for command

By default the module with search for configuration in ./comment-to-doc.config.js,

Example config file (comment-to-doc.config.js)

This is the very same configuration described above in Configuration section

const { defaultTags } = require('./lib')

module.exports = {
  files: [
    './tests-input.tsx',
  ],
  tags: defaultTags,
  output: () => './cli-output.md'
};

Default tags

• @Title
• @Title2
• @Title3
• @Title4
• @Title5
• @Title6
• @Usage
• @Description
• @Default
• @Bold
• @Italic
• @Crossover
• @Img
• @Image
• @Quote
• @Code
• @Custom
• @Date
• @Table
• @Column
• @Row
• @Object
• @Key

For usage, see:

• Input: tests-input.tsx
• Output: tests-output.md

Want to play around a bit?

1. Clone or fork this repository.
2. npm install
3. Edit tests-input.tsx file
4. npm run try
5. See tests-output.md for results

Tests

npm test to run tests

Your own tags

If you come up with your own cool tags, you can send me a link to your repository, so I could add it here in this documentation.