{"id":19607893,"url":"https://github.com/mkdoc/mkapi","last_synced_at":"2025-04-27T20:32:28.540Z","repository":{"id":57298819,"uuid":"52410710","full_name":"mkdoc/mkapi","owner":"mkdoc","description":"Markdown API documentation generator","archived":true,"fork":false,"pushed_at":"2018-01-09T01:21:45.000Z","size":271,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T00:46:13.469Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkdoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-24T03:16:46.000Z","updated_at":"2024-12-11T22:13:07.000Z","dependencies_parsed_at":"2022-08-26T18:12:37.405Z","dependency_job_id":null,"html_url":"https://github.com/mkdoc/mkapi","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkdoc","download_url":"https://codeload.github.com/mkdoc/mkapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251204565,"owners_count":21552239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T10:12:53.058Z","updated_at":"2025-04-27T20:32:28.048Z","avatar_url":"https://github.com/mkdoc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown API\n\n[![Build Status](https://travis-ci.org/mkdoc/mkapi.svg?v=5)](https://travis-ci.org/mkdoc/mkapi)\n[![npm version](http://img.shields.io/npm/v/mkapi.svg?v=5)](https://npmjs.org/package/mkapi)\n[![Coverage Status](https://coveralls.io/repos/mkdoc/mkapi/badge.svg?branch=master\u0026service=github\u0026v=5)](https://coveralls.io/github/mkdoc/mkapi?branch=master)\n\n\u003e API documentation generator\n\nDeclarative, extensible, language neutral and fast API comments to commonmark compliant markdown.\n\nDesigned for small to medium sized libraries, for large projects use one of the many other documentation tools. Uses `javascript` for fenced code blocks by default but you can [configure](#conf) this library for any language.\n\nSee [EXAMPLE.md](https://github.com/mkdoc/mkapi/blob/master/EXAMPLE.md) or the [api](#api) for example output.\n\n## Install\n\n```\nnpm i mkapi --save\n```\n\nFor the command line interface install [mkdoc][] globally (`npm i -g mkdoc`).\n\n---\n\n- [Install](#install)\n- [Usage](#usage)\n- [Example](#example)\n- [Comments](#comments)\n- [Description](#description)\n- [Tags](#tags)\n  - [Meta Tags](#meta-tags)\n  - [Notice Tags](#notice-tags)\n  - [General Tags](#general-tags)\n  - [Type Tags](#type-tags)\n  - [Modifier Tags](#modifier-tags)\n  - [Function Tags](#function-tags)\n  - [Property Tags](#property-tags)\n  - [Shorthand Tags](#shorthand-tags)\n  - [Name](#name)\n  - [Module](#module)\n  - [Class](#class)\n  - [Constructor](#constructor-NaN)\n  - [Inherits](#inherits)\n- [Cues](#cues)\n  - [Member](#member)\n  - [Static](#static)\n  - [Inheritance](#inheritance)\n- [Help](#help)\n- [API](#api)\n  - [parse](#parse)\n  - [register](#register)\n  - [tag](#tag)\n  - [Tag](#tag-1)\n- [Comment](#comment)\n  - [.getDetail](#getdetail)\n  - [.getInfo](#getinfo)\n  - [.find](#find)\n  - [.collect](#collect)\n  - [conf](#conf)\n  - [formats](#formats)\n  - [render](#render)\n  - [writers](#writers)\n- [License](#license)\n\n---\n\n## Usage\n\nPass files and options:\n\n```javascript\nvar parse = require('mkapi');\nparse(['index.js'], {output: process.stdout});\n```\n\n## Example\n\nPrint the documentation to stdout:\n\n```\nmkapi index.js\n```\n\nCreate a markdown document from the comments in a source file:\n\n```shell\nmkapi index.js --title=API -o API.md\n```\n\nSet initial heading level:\n\n```shell\nmkapi index.js --title=API --level=2 -o API.md\n```\n\nInclude private symbols in the output:\n\n```shell\nmkapi index.js --private -o API.md\n```\n\n## Comments\n\nComments are parsed from `/**...*/` at the moment, later the aim is to support other styles of comment declarations.\n\n## Description\n\nWhilst many [tags](#tags) allow for a description parameter it is recommended that the description starts the comment so that it is more prominent.\n\n```javascript\n/**\n *  Module description.\n *\n *  @module ModuleName\n */\n```\n\nIf you only have a short description use the `description` tag parameter:\n\n```javascript\n/**\n *  @module ModuleName Short module description.\n */\n```\n\n## Tags\n\nThe general syntax for tags is:\n\n```javascript\n@tag {type} name description\n```\n\nWhen a tag name is enclosed in `[]` it is deemed to be optional, for example:\n\n```javascript\n/**\n *  @name {function} noop\n *  @param {Function} [cb] Callback function.\n */\n```\n\n### Meta Tags\n\nMeta tags are rendered as a list at the top of the block below the symbol description:\n\n* `@author`: Author meta data.\n* `@version`: Version information.\n* `@since`: Since version.\n* `@license`: License information.\n\n### Notice Tags\n\nNotice tags are rendered as blockquote elements at the top or below meta tags when present:\n\n* `@deprecated`: Flag symbol as deprecated.\n* `@todo`: Note something yet to be done.\n\n### General Tags\n\nThe following tags are ways to add information to the output.\n\n* `@name`: Sets the symbol name and optionally the symbol type.\n* `@usage`: Usage example(s) that appear below the first heading.\n* `@see`: Creates a list of links, each value should be a URL if a description is given it becomes the name for the link.\n\n### Type Tags\n\nA type tag maps to a render function, see the [render api docs](#render).\n\n* `@module`: Symbol is a module.\n* `@class`: Symbol is a class.\n* `@constructor`: Symbol is a constructor function.\n* `@function`: Symbol is a function.\n* `@property`: Symbol is a property.\n\nYou can specify the type using the tag itself:\n\n```javascript\n/**\n *  @function getName  \n *  @protected\n */\n```\n\nOr you can use [shorthand tags](#shorthand-tags):\n\n```javascript\n/**\n *  @protected {function} getName\n */\n```\n\n### Modifier Tags\n\nModifier tags give information about a symbol:\n\n* `@inherits`: Indicates the super class hierarchy for `@constructor` or `@class`.\n* `@member`: Symbol is a member of an object.\n* `@static`: Symbol is static.\n* `@constant`: Constant symbol, implies `@readonly`.\n* `@private`: Member is private, excluded from the output by default.\n* `@protected`: Member is protected.\n* `@public`: Member is public.\n* `@abstract`: Member is abstract.\n* `@readonly`: Member is read-only.\n\n### Function Tags\n\nTags specific to the `{function}` type:\n\n* `@param`: Declares an argument for a function.\n* `@option`: Documents an option property.\n* `@throws`: Function throws exception(s).\n* `@returns`: Document a return value.\n\n### Property Tags\n\nTags specific to the `{property}` type:\n\n* `@default`: Default value for a property.\n\n### Shorthand Tags\n\nType identifiers may be specified to some tags using a type `{id}`, the syntax is:\n\n```javascript\n@tag {type} \u003cname\u003e [description]\n```\n\n* `@name`: Set the name and type.\n* `@static`: Set the name, type and mark as static.\n* `@constant`: Set the name, type and mark as a constant.\n* `@public`: Set the name, type and mark as public.\n* `@private`: Set the name, type and mark as private.\n* `@protected`: Set the name, type and mark as protected.\n* `@member`: Declare as member, set the symbol type.\n\nFor example to declare a `function` symbol with the name `noop`:\n\n```javascript\n@name {function} noop\n```\n\n### Name\n\n```javascript\n@name [{type}] \u003cname\u003e\n```\n\nSets the symbol name and optionally specifies the type of the symbol (see [type tags](#type-tags)).\n\n```javascript\n/**\n *  @name {function} FunctionName\n */\n```\n\n```javascript\n/**\n *  @name FunctionName\n *  @function\n */\n```\n\n### Module\n\n```javascript\n@module \u003cname\u003e\n```\n\nDocument a module.\n\n```javascript\n/**\n *  Module description.\n *\n *  @module ModuleName\n */\n```\n\n### Class\n\n```javascript\n@class \u003cname\u003e\n```\n\nDocument a class.\n\n```javascript\n/**\n *  Class description.\n *\n *  @class ClassName\n */\n```\n\n### Constructor\n\n```javascript\n@constructor \u003cname\u003e\n```\n\nDocument a constructor function.\n\n```javascript\n/**\n *  Constructor description.\n *\n *  @constructor ConstructorName\n */\n```\n\n### Inherits\n\n```javascript\n@inherits \u003csuperclass...\u003e\n```\n\nDocument inheritance hierarchy for a constructor function or class.\n\n```javascript\n/**\n *  Constructor description.\n *\n *  @constructor ConstructorName\n *  @inherits EventEmitter Object\n */\n```\n\n## Cues\n\nThe generated markdown includes certain visual cues in headings:\n\n### Member\n\n```\n.member\n```\n\nIndicates a class member.\n\n### Static\n\n```\n#member\n```\n\nIndicates a static class member, borrowed from HTML identifiers.\n\n### Inheritance\n\n```\nSubClass : SuperClass\n```\n\nIndicates an inheritance hierarchy.\n\n## Help\n\n```\nUsage: mkapi [-ah] [--ast] [--[no]-private] [--[no]-protected] [--help]\n             [--version] [--output=\u003cfile\u003e] [--title=\u003cval\u003e] [--level=\u003cnum\u003e]\n             [--lang=\u003clang\u003e] [--indent=\u003cnum\u003e] \u003cfiles...\u003e\n\n  Documentation generator.\n\nOptions\n  -o, --output=[FILE]     Write output to FILE (default: stdout)\n  -t, --title=[VAL]       Title for initial heading\n  -l, --level=[NUM]       Initial heading level (default: 1)\n  -L, --lang=[LANG]       Language for fenced code blocks (default: javascript)\n  -i, --indent=[NUM]      Number of spaces for JSON (default: 2)\n  -a, --ast               Print AST as JSON\n  --[no]-private          Enable or disable private symbols\n  --[no]-protected        Enable or disable protected symbols\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmkapi@1.2.2\n```\n\n## API\n\n### parse\n\n```javascript\nparse(files[, opts], cb)\n```\n\n```javascript\nvar parse = require('mkapi')\n  , parse(['index.js'], {output: process.stdout});\n```\n\nAccepts an array of files and iterates the file contents in series\nasynchronously.\n\nParse the comments in each file into a comment AST\nand transform the AST into commonmark compliant markdown.\n\nThe callback function is passed an error on failure: `function(err)`.\n\nReturns an event notifier.\n\n* `files` Array List of files to parse.\n* `opts` Object Parse options.\n* `cb` Function Callback function.\n\n#### Options\n\n* `output` Writable The stream to write to, default is `stdout`.\n* `conf` Object Configuration overrides.\n* `level` Number Initial level for the first heading, default is `1`.\n* `title` String Value for an initial heading.\n* `lang` String Language for fenced code blocks, default is `javascript`.\n* `parser` Object Options to pass to the `mkparse` library.\n\n#### Events\n\n* `error` when a processing error occurs.\n* `file` when a file buffer is available.\n* `ast` when the comment AST is available.\n* `finish` when all files have been parsed.\n\n### register\n\n```javascript\nregister(type[, renderer])\n```\n\nRegister a render function for a given type tag.\n\nWithout the `renderer` option attempts to return a render function\nfor the specified type.\n\nReturns a renderer or the registry.\n\n* `type` String The type name for the tag.\n* `renderer` Function The render function.\n\n### tag\n\n```javascript\ntag(name[, opts])\n```\n\nAdds a tag to the list of known tags.\n\nUse this to create custom tags.\n\nReturns the tag definition.\n\n* `name` String The name of the tag, do not include `@`.\n* `opts` Object An object whose fields are merged with the tag\ndefinition.\n\n### Tag\n\n```javascript\nnew Tag()\n```\n\nEncapsulates a tag definition.\n\n## Comment\n\nEncapsulates operations on a comment AST token.\n\nThis implementation uses a cache map to look up tags in the\nunderlying list of tags.\n\n### .getDetail\n\n```javascript\ngetDetail.prototype.getDetail([names])\n```\n\nGet the details name, type tag and id for this comment.\n\nReturns an object with `name`, `type` and `id`.\n\n* `names` Array List of custom tag names.\n\n### .getInfo\n\n```javascript\ngetInfo.prototype.getInfo(method)\n```\n\nGets an info object containing generic tag lookups.\n\nIf the `method` parameter is given the object is decorated with\nfields specific to the `function` type.\n\n* `method` Boolean Inject function specific information.\n\n### .find\n\n```javascript\nfind.prototype.find(id)\n```\n\nFinds the last tag in the tag list by tag id.\n\nReturns a tag or `undefined` if not found.\n\n* `id` String The tag identifier.\n\n### .collect\n\n```javascript\ncollect.prototype.collect(id)\n```\n\nCollects all tags with the specified id.\n\nReturns an array of tags.\n\n* `id` String The tag identifier.\n\n### conf\n\nEvery aspect of the program output may be modified by changing the\nconfiguration variables.\n\nConstants representing each of the recognised tags are exposed on this\nmodule, for example: `this.conf.MODULE` yields `module`.\n\n#### names\n\n```javascript\nArray names\n```\n\nList of default tag names.\n\n#### title\n\n```javascript\nObject title\n```\n\nVariables for headings and notices, eg: `Deprecated`.\n\n#### shorthand\n\n```javascript\nArray shorthand\n```\n\nList of tag names that support the shorthand symbol type.\n\n#### format\n\n```javascript\nObject format\n```\n\nMap of format functions.\n\n#### See Also\n\n* [formats module](#formats \"formats module\")\n\n#### cues\n\n```javascript\nObject cues\n```\n\nMap of variables for visual cues.\n\n#### render\n\n```javascript\nObject render\n```\n\nMap of render functions.\n\n#### See Also\n\n* [render module](#render \"render module\")\n\n#### include\n\n```javascript\nObject include\n```\n\nMap of symbol types to include.\n\n#### LANG\n\n```javascript\nString LANG = javascript;\n```\n\nDefault language for fenced code blocks.\n\n### formats\n\nProvides string format functions.\n\n#### heading\n\n```javascript\nheading(val, level)\n```\n\nGets a heading string.\n\nReturns the heading.\n\n* `val` String The value for the heading.\n* `level` Number The level for the heading.\n\n#### meta\n\n```javascript\nmeta(val, title)\n```\n\nGets a list item for the meta data.\n\nReturns a list item for the meta data.\n\n* `val` Object The value for the heading.\n* `title` String A prefix for the meta item.\n\n#### fenced\n\n```javascript\nfenced(code, info)\n```\n\nGets a fenced code block.\n\nReturns a fenced code block.\n\n* `code` String The content for the code block.\n* `info` String A language info string.\n\n#### deprecated\n\n```javascript\ndeprecated(tag)\n```\n\nGets a deprecated notice.\n\nReturns a deprecation notice.\n\n* `tag` Object The deprecated tag.\n\n#### signature\n\n```javascript\nsignature(params)\n```\n\nGets a function signature.\n\nReturns a function signature.\n\n* `params` Array Collection of param tags.\n\n#### parameter\n\n```javascript\nparameter(tag)\n```\n\nGets a list item for parameter listings.\n\nReturns a parameter list item.\n\n* `tag` Object The param tag.\n\n#### returns\n\n```javascript\nreturns(token, tag)\n```\n\nGets a returns statement.\n\nReturns the returns value.\n\n* `token` Object the current AST token.\n* `tag` Object The returns tag.\n\n#### link\n\n```javascript\nlink(tag)\n```\n\nGets a link from a tag.\n\nReturns formatted string.\n\n* `tag` Object The see tag.\n\n#### getAccess\n\n```javascript\ngetAccess(opts)\n```\n\nGets the access modifier for a symbol.\n\nReturns the access for the symbol.\n\n* `opts` Object Format options describing the symbol.\n\n#### property\n\n```javascript\nproperty(tag, opts)\n```\n\nGets a property code string.\n\nReturns formatted string.\n\n* `tag` String The declaring tag.\n* `opts` Object Format options describing the property.\n\n#### inherits\n\n```javascript\ninherits(tag, opts)\n```\n\nGets the inheritance string for a class or constructor.\n\n* `tag` Object The declaring tag.\n* `opts` Object Format options describing the function.\n\n#### method\n\n```javascript\nmethod(tag, opts[, title])\n```\n\nGets the heading title for a function.\n\n* `TODO` remove magic strings.\n* `tag` Object The declaring tag.\n* `opts` Object Format options describing the function.\n* `title` String An existing title for the function.\n\n#### getTodo\n\n```javascript\ngetTodo(tag)\n```\n\nGets the todo list.\n\nReturns The list of todo items.\n\n* `TODO` remove magic strings.\n* `tag` Object The declaring tag.\n\n### render\n\nDefault render functions.\n\nRender functions are called asynchronously and must invoke the callback\nfunction to process the next comment.\n\n#### _class\n\n```javascript\n_class(type, token, cb)\n```\n\nRender a class (or module) block.\n\n* `type` Object The tag that initiated the render.\n* `token` Object The current comment AST token.\n* `cb` Function Callback function.\n\n#### _function\n\n```javascript\n_function(type, token, cb)\n```\n\nRender a function block.\n\n* `type` Object The tag that initiated the render.\n* `token` Object The current comment AST token.\n* `cb` Function Callback function.\n\n#### _property\n\n```javascript\n_property(type, token, cb)\n```\n\nRender a property block.\n\n* `type` Object The tag that initiated the render.\n* `token` Object The current comment AST token.\n* `cb` Function Callback function.\n\n### writers\n\nOutput writer helper functions.\n\nResponsible for writing to the output output but should **not** perform\nany formatting of the output string, their role is to extract the\nrelevant information; call a format function and write the result to\nthe output appending newlines where necessary.\n\nRender functions can access these methods using `this`.\n\nThese functions call the format functions using `this.format`.\n\n#### heading\n\n```javascript\nheading(val, level)\n```\n\nWrite a heading at the specified level.\n\n* `val` String The value for the heading.\n* `level` Number The level for the heading.\n\n#### newline\n\n```javascript\nnewline([num])\n```\n\nWrite one or more newlines.\n\n* `num` Number The number of newlines to print, default is 1.\n\n#### fenced\n\n```javascript\nfenced(code)\n```\n\nWrite a fenced code block.\n\n* `code` String The code content for the fenced block.\n\n#### signature\n\n```javascript\nsignature(params, name, lang)\n```\n\nWrite a function signature as a fenced code block.\n\n* `params` Array List of tags.\n* `name` String A name for the function.\n* `lang` String A language for the info string.\n\n#### parameters\n\n```javascript\nparameters(params)\n```\n\nWrite a list of parameters.\n\nUsed for writing param, option, throws etc.\n\n* `params` Array List of tags.\n\n#### meta\n\n```javascript\nmeta(token)\n```\n\nWrite meta data (author, version, since etc) and handle writing the\ndeprecated notice.\n\n* `token` Object The current token.\n\n#### describe\n\n```javascript\ndescribe(type, token)\n```\n\nPrint the description for a token.\n\n* `type` Object The declaring type tag.\n* `token` Object The current token.\n\n#### see\n\n```javascript\nsee(token, depth)\n```\n\nWrite the list of see also links.\n\n* `token` Object The current token.\n* `depth` Number The current heading depth.\n\n#### Writer : EventEmitter\n\n```javascript\nnew Writer()\n```\n\nWriter helper functions, an instance of this class is\nthe scope for program execution and is decorated with additional\nfields when parse is called.\n\n## License\n\nMIT\n\n---\n\nCreated by [mkdoc](https://github.com/mkdoc/mkdoc) on February 10, 2017\n\n[mkdoc]: https://github.com/mkdoc/mkdoc\n[jshint]: http://jshint.com\n[jscs]: http://jscs.info\n[commonmark]: https://github.com/jgm/commonmark.js\n[mdp]: https://github.com/tmpfs/mdp\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkdoc%2Fmkapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkapi/lists"}