-
Notifications
You must be signed in to change notification settings - Fork 105
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.]
- Allow users to view info about a tag by invoking JSDoc on the command line.
- Make it possible to integrate the tag docs into the Jake build process for usejsdoc.org.
- Provide a way to document new tags that are defined by plugins.
- 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.)
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 definitions.js
file will be refactored to provide additional information for use in the docs. In addition, each language-specific directory will contain a Markdown file for each tag, using the name <primaryTagName>.md
. These files are described below.
The definitions.js
file will be refactored so that all of the tag definitions are defined in a single object. The following example shows how the object will be formatted:
{
tagname: {
// info needed by JSDoc, but probably not needed for the docs
mustHaveValue: true,
canHaveType: true,
onTagged: function(doclet, tag) {
doclet.tagname = tag.value;
},
// info needed by both
synonyms: ['tagsynonym', 'tagsynonym2'], // or a string if there's only one synonym
// new info for the docs
summary: { // or a string if there's only an English version
en: 'A brief description of the tag.'
},
syntax: { // or a string if there's only an English version
en: '@tagname [{type}] description'
},
seeAlso: ['sometag', 'someothertag'] // or a string if there's only one related tag
},
tagname2: {
// et cetera
}
};
When the object is accessed, synonyms will be added programmatically, so they can be looked up without iterating over the tag definitions. The resulting object will look like the following example:
{
tagname: {
// see above example
// has two synonyms: 'tagsynonym' and 'tagsynonym2'
},
tagname2: {
// like tagname
},
tagsynonym: {
see: 'tagname'
},
tagsynonym2: {
see: 'tagname'
}
}
For each tag, we will create a Markdown file that provides detailed information about the tag. The Markdown file will be named <primaryTagName>.md
. [TODO: Can we make it pure Markdown, or do we need to keep some templating stuff in there for the website? It would be nicer for authors if the templating stuff could be added programmatically when the docs are built.]
As a general rule, the Markdown docs for each tag should include top-level "overview" and "examples" sections. [TODO: Other rules needed?]
[TODO: Do we need any info from the Markdown files to show command-line help? I would think not, but if we do, maybe use html-to-text?]
[TODO: Discuss the following options and choose one]
-
jsdoc help --tags
(all tags),jsdoc help --tags 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
-
jsdoc --help:tags
(all tags),jsdoc --help:tags event
(just@event
),jsdoc --help:tags event,fires
(@event
and@fires
)- @micmath's suggestion
- Other options?
Describe how plugin authors can document a plugin-defined tag.