Naive Puppets Marching

    comment-to-doc
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.24 • Public • Published

    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:

    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.

    Install

    npm i comment-to-doc

    DownloadsWeekly Downloads

    42

    Version

    1.2.24

    License

    MIT

    Unpacked Size

    112 kB

    Total Files

    42

    Last publish

    Collaborators

    • alexsapoznikov