Metarhia Documentation Generator

Installation

$ npm install -g @metarhia/doc

Cli usage

metadoc [options] file.js [file.js...]

Options:
  --help                 Show help                                     [boolean]
  --version              Show version number                           [boolean]
  --header               header for the resulting doc file              [string]
  --footer               footer for the resulting doc file              [string]
  --header-file          file with header for the resulting doc file    [string]
  --footer-file          file with footer for the resulting doc file    [string]
  --write-to-stdout, -o  write output to stdout instead of files       [boolean]
  --output-dir, -d       output directory for separate doc files        [string]
  --output-file, -f      output directory for merged doc file           [string]
  --config, -c           custom config file                             [string]

API

Table of Contents

• introspect
• parseSignature
• generateMd

introspect(namespace, text)

• namespace: <Map> hash of interfaces
• text: <string> data to parse

Returns: <Map> hash of hash of records, { title, description, parameters, comments }

Introspect interface

parseSignature(fn, text, start)

• fn: <Function>|<RegExp> to be searched
• text: <string> to be searched in
• start: <number> position to start searching from

Returns: <Object> function signature

• title: <string> short function description
• description: <string> extended function description
• argsSignature: <string> custom function signature
• parameters: <Object[]> function parameters, { name, types, nonStandardTypes, comment, offset }
• comments: <Object[]> comments about returned value, thrown errors, deprecation and usage, { name, types, nonStandardTypes, comment }

Parse function signature

generateMd(inventory, options)

• inventory: <Map> hash of map of records, { method, title, parameters }
• options: <Object>
  • header: <string> text before api documentation
  • footer: <string> text after api documentation
  • customTypes: <string[]> custom types
  • customLinks: <Array[]> custom types links

Returns: <string> md document

Generate md from interfaces inventory

Contributors

See GitHub for a full list of contributors

License

Licesed under MIT license. Copyright (c) 2018 Metarhia contributors

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.7.0 - 2020-08-16

Added

• Support separating title and description of function via separateTitleDescription field in config file or --separate-title-description cli flag. By default, title and description will be separated.
• Support for complex/nested types in declarations.

Fixed

• Generation of custom refs with '#' sign in them.
• Multiple refs on single line.

0.6.1 - 2020-06-03

Update dependencies and bump version.

0.6.0 - 2019-12-30

Added

• Support generating contents table for API.
• Support for nested fields of properties.
• Support adding namespace prefix to the entities names.
• Support for BigInt64Array and BigUint64Array types.
• Support ordering documentation entries.

Changed

• Use main field from package.json as default file if available.
• Generate class links.
• Support overriding default types links.

Fixed

• Handle documentation generation when function parameters have incorrect padding.
• Do not generate extra empty line after links if there are no links.
• Generation of custom signatures with default values.

0.5.6 - 2019-05-31

Added

• Support for prettier-ignore comment.
• Sort generated methods by name.
• Allow to disable generating documentation for functions with #private header in the documentation comment. Documentation for such functions will not be generated by default. This can be changed via private field in config file or --private cli flag.

Fixed

• eslint-disable comments processing
• Support for functions definitions in parameters.
• Class constructor handling.
• Class instance handling.

0.5.5 - 2019-05-11

Added

• Support for functions in nested arrays.

0.5.4 - 2019-05-10

Added

• Support for functions in nested objects.
• Support for the following types:
  • Proxy
  • URIError
  • Intl.Collator
  • Intl.DateTimeFormat
  • Intl.ListFormat
  • Intl.NumberFormat
  • Intl.PluralRules
  • Intl.RelativeTimeFormat
  • WebAssembly.Global
  • WebAssembly.Module
  • WebAssembly.Instance
  • WebAssembly.Memory
  • WebAssembly.Table
  • WebAssembly.CompileError
  • WebAssembly.LinkError
  • WebAssembly.RuntimeError

0.5.3 - 2019-05-07

Added

• Support for parameter function Returns: comment.
• Support for Promise type.
• This CHANGELOG.md file.

Fixed

• Custom embedded comments links.

0.5.2 - 2019-04-26

Added

• Support for static properties.
• Support for multiple signatures.

Fixed

• Class constructor comments parsing

0.5.1 - 2019-04-24

Added

• Support for custom comments links.
• Support for functions in namespace.
• Allow specifying headers level. Headers level for interface name, top-level functions, classes, class methods, class static methods, properties can be specified individually via --interface-level, --function-level, --class-level, --method-level, --static-method-level, --property-level cli options or interfaceLevel, functionLevel, classLevel, methodLevel, staticMethodLevel, propertyLevel config options.

Changed

• Create output directory if it does not exist.

Fixed

• One argument lambda functions parsing.
• Complex array type generation.

0.5.0 - 2019-04-15

Added

• Support for class inheritance.
• Support for getters and setters. They can be specified via Properties: comment.

0.4.1 - 2019-04-11

Added

• Allow to specify minimal header level via --min-header-level cli option or minHeaderLevel config option.

0.4.0 - 2019-04-10

Added

• Support for functions native arguments generation. If neither Signature: comment nor parameters were specified arguments from function code will be used instead.

Changed

• Escape underscore in headers.
• Add a semicolon at the end of Example and Result if there is no one.
• Generate class prefix.

Fixed

• Embeded code generation.

0.3.0 - 2019-04-05

Changed

• Md generation will be compatible with prettier.

0.2.1 - 2019-03-25

Added

• --no-config cli option.
• Support for class properties via Properties: comment.
• Support for async functions.

Changed

• Title is optional.
• Add explicit brackets after types links.
• Use .metadocrc as default config.
• Do not generate extra empty lines between functions.

Removed

• Dropped support for Node.js 6.

Fixed

• Folders which should be parsed can be specified along with files in cli and via config files option.

0.2.0 - 2019-02-16

Added

• Function arguments signature can be specified via Signature: comment. It will overwrite arguments based on parameters comments.
• Interface name generation can be disabled via --remove-interface cli option or removeInterface config option.
• Support for rest operator.
• Support for BigInt type.
• Support for eslint-disable-next-line.

Changed

• Type(s) in function arguments are optional.
• Comments in function arguments are optional.
• Type(s) in title, description, function comments and arguments comments will be wrapped in markdown.

Fixed

• Array type parsing.
• Cli arguments priority.
• Do not generate extra empty line after arguments.
• Empty class constructor parsing.

0.1.0 - 2019-01-18

Added

• The first implementation of the package.