documentation-schema

api-json

api-json is a documentation data standard. It can be generated by documentation engines like documentationjs or written by hand.

api-json enables a two stage documentation process:

1. documentation extraction or authorship
2. output formatting

Maximum example

{
  "name": "sort",
  "kind": "function",
  "description": "Create a stream.Transform that sorts its input of comments\nby the name tag, if any, and otherwise by filename.",
  "memberof": "module",
  "scope": "static",
  "context": {
    "loc": {
      "start": {
        "line": 9,
        "column": 0
      },
      "end": {
        "line": 23,
        "column": 2
      }
    },
    "file": "/Users/tmcw/src/documentation/streams/sort.js",
    "code": "var sort = require('sort-stream');\n\n/**\n * Create a stream.Transform that sorts its input of comments\n * by the name tag, if any, and otherwise by filename.\n * @name sort\n * @return {stream.Transform} a transform stream\n */\nmodule.exports = function () {\n\n  function getSortKey(comment) {\n    for (var i = 0; i < comment.tags.length; i++) {\n      if (comment.tags[i].title === 'name') {\n        return comment.tags[i].name;\n      }\n    }\n    return comment.context.file;\n  }\n\n  return sort(function (a, b) {\n    return getSortKey(a).localeCompare(getSortKey(b));\n  });\n};"
  },
  "returns": [
    {
      "title": "returns",
      "description": "a transform stream",
      "type": {
        "type": "NameExpression",
        "name": "stream.Transform"
      }
    }
  ]
}

Minimal example

{
  "name": "sort",
  "kind": "function",
  "description": "Create a stream.Transform that sorts its input of comments\nby the name tag, if any, and otherwise by filename.",
  "memberof": "module",
  "scope": "static",
  "returns": [
    {
      "title": "returns",
      "description": "a transform stream",
      "type": {
        "type": "NameExpression",
        "name": "stream.Transform"
      }
    }
  ]
}

Meaning

{
  "name": // this is the name of the function, object, class, or namespace
  "kind": // http://usejsdoc.org/tags-type.html
  "description": // http://usejsdoc.org/tags-description.html
  "memberof": // http://usejsdoc.org/tags-memberof.html
  "scope": // http://usejsdoc.org/tags-instance.html
  "context": {
    "loc": {
      // this contains 'start' and 'end' objects in the same style
      // as the esprima javascript parser
    },
    "file": // absolute path to the relevant source code
    "code": // extracted source code, potentially excerpted
  },
  "returns": [
    {
      "title": "returns",
      "description": "a transform stream",
      "type": {
        "type": "NameExpression",
        "name": "stream.Transform"
      }
    }
  ],
  "params": [
    ...
  ],
  "throws": [
    ...
  ]
}