Tag Documentation Spec

This page provides requirements and a high-level specification for adding built-in tag documentation to JSDoc, and for providing a command-line interface to the tag docs.

[TODO: Once this spec is more or less final, use it as a starting point for a plugin documentation spec.]

Requirements

1. Allow users to view info about a tag by invoking JSDoc on the command line.
2. Make it possible to integrate the tag docs into the Jake build process for usejsdoc.org.
3. Provide a way to document new tags that are defined by plugins.
4. Make sure it's possible to translate the docs into other languages later on. (We don't need support for translated docs now, but it should be possible to add this later without breaking everything.)

Specification

File Structure

JSDoc's built-in tags are defined in rhino_modules/jsdoc/tag/dictionary/definitions.js.

A new docs/ directory will be added at the same level as definitions.js. For each supported language, the docs/ directory will contain a subdirectory named after the language's ISO 639-1 code. At this time, the only subdirectory will be en/. All docs must, at a minimum, be available in English.

The docs/ directory will contain a JSON file for each tag, using the name <primaryTagName>.json. Each language-specific directory will contain a Markdown file for each tag, using the name <primaryTagName>.md. These files are described below.

JSON File Format

For each tag, we will create a JSON file that contains all of the information needed to provide an overview of the tag.

For the primary tag name, the JSON file will use the following format: [TODO: Anything missing?]

{
  "name": "tagname",
  // or, if there's only one synonym, use "synonyms": "synonym1"
  "synonyms": ["synonym1", "synonym2"],

  // or, if there's only English, use "summary": "blah blah"
  "summary": {
    "en": "A brief description of the tag."
  },
  "syntax": "@tagname [{type}] description",
  "seeAlso": ["sometag"],

  // or, if there's only English, use "docs": "./docs/en/tagname.md"
  "docs": {
    "en": "./docs/en/tagname.md"
  }
}

For synonyms of the primary tag name, the JSON file will use the following format, which allows JSDoc to locate the correct docs quickly and efficiently:

{
  "see": "tagname"
}

Markdown File Format

For each tag, we will create a Markdown file that provides detailed information about the tag. [TODO: Can we make it pure Markdown, or do we need to keep some templating stuff in there for the website? If we need templating stuff, could we put it in HTML comments, then convert it to the right format during the build process?]

As a general rule, the Markdown docs for each tag should include top-level "overview" and "examples" sections.

[TODO: Other rules needed?]

[TODO: Decide how to format the info for the command line. Maybe use html-to-text?]

Command-Line Syntax

[TODO: Discuss the following options and choose one]

1. jsdoc help --tags (all tags), jsdoc help --tag event (just @event), jsdoc help --tags event,fires (@event and @fires)
   • @hegemonic's preference
   • Similar to command-line tools that many JavaScript developers use, such as git, npm, bower, and yeoman
   • Extensible; for example, if we add a daemon mode that rebuilds the docs when JS files change, the syntax could be jsdoc watch
2. jsdoc --help:tags (all tags), jsdoc --help:tags event (just @event), jsdoc --help:tags event,fires (@event and @fires)
   • @micmath's suggestion
3. Other options?

TODO

Describe how plugin authors can document a plugin-defined tag.