amd-doc
v0.2.2
Published
Documentation generator for AMD-based projects
Downloads
12
Readme
amd-doc
amd-doc is a JavaScript documentation generator for AMD-based projects. It post-processes the JSON output of jsdoc3, using RequireJS configuration and AMD conventions to infer more information.
Installation
npm install amd-doc
Usage
The main functionality of amd-doc is exposed through the compile
function. It
returns a Deferred object
and accepts an opts
argument which can contain these properties (example from
deferreds.js):
var amddoc = require('amd-doc');
amddoc.compile({
//globbing-supported String or Array of Strings with process-relative
//files to process for documentation
include: 'src/deferreds/**/*.js',
//directory to output generated HTML (default = 'doc/out')
out: 'doc/out',
//directory to store jsdoc cache (default = 'doc/cache')
cache: 'doc/cache',
//directory to look for markdown mixins (default = 'doc/mixin')
mixin: 'doc/mixin',
//github URL where source is available. the file path and line number of
//each documented variable will be added to this to make source links.
repoview: 'https://github.com/zship/deferreds.js/blob/develop/',
//Array of Type (see tasks/doc/Types.js) objects to transform into links
//when used as parameter types, return types, or description namepaths
types: (function() {
var types = [];
//make all built-in types link to their MDN pages
['Number', 'String', 'Object', 'Function', 'Array', 'RegExp', 'Boolean'].forEach(function(val) {
types.push({
name: val,
link: 'https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/' + val
});
});
types.push({
name: 'Any',
link: 'https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects'
});
types.push({
name: 'void',
link: 'https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/undefined'
});
types.push({
name: 'Element',
link: 'https://developer.mozilla.org/en-US/docs/DOM/element'
});
types.push({
name: 'jQuery',
link: 'http://api.jquery.com/jQuery/'
});
types.push({
name: 'require',
link: 'http://requirejs.org/'
});
types.push({
//any name matching this RegExp (with name.search()) will be given
//the following link
regexp: /amd-utils\/.*/,
link: 'http://millermedeiros.github.com/amd-utils/'
});
return types;
})(),
//requirejs configuration object
//more: https://github.com/jrburke/r.js/blob/master/build/example.build.js
//amd-doc uses `basePath`, `paths`, and `packages` (all optional) to
//transform file names to AMD module names.
requirejs: {
baseUrl: 'src/deferreds',
optimize: 'none',
packages: [
{ name: 'amd-utils', location: '../lib/amd-utils' }
],
}
});
What it does
Inferred information
- Class names
- Convention: one class per file - names the class after the last part of the module name (e.g. 'joss/geometry/Rect' -> 'Rect')
- When using
@lends
, any name may be specified and it will be replaced by the last part of the module name (i.e./** @lends __.prototype */
will apply its properties to the only class defined in the file, regardless of the existence of a variable__
)
- Namespace names
- Convention: one namespace per file - names the namespace after the last part of the module name
@namespace
may be used by itself (with no name to assign to the namespace)
- Dependencies
- AMD dependencies of each file are included in the output
Other Additions
- Cache jsdoc output
- jsdoc3 is very comprehensive, but suffers from poor performance. amd-doc tries to compensate by maintaining a per-file cache, with freshness determined by hashing each source file's contents and comparing on each run.
- Type system
- Every declared class will, on declaration, have a Type object associated with it (see tasks/doc/Types.js). These Types contain both long names (full module names) and short names (last part of the module name) and are used to match against AMD dependencies, parameters, return types, and namepaths in descriptions.
- External types like {String} and {Object} can be specified in the configuration object, to present links in the output. (e.g. {String} can become String, linking to MDN's String reference)
- Mixing-in markdown documentation from external files
- Markdown files can be specified in a directory structure mirroring your
source, one per source file. Any
h2
s (##
) in the file will be matched against variable names in your source, and content under theh2
will replace the description for that variable
- Markdown files can be specified in a directory structure mirroring your
source, one per source file. Any
- Converting jsdoc namepaths or Type names to links within descriptions
- Specify namepaths between braces
{}
, and if there is a matching documented variable, the namepath will be converted to a link. {joss/geometry/Rect#moveTop}
becomes Rect.moveTop{Rect#moveTop}
also becomes Rect.moveTop, if the short-name "Rect" is not declared more than once{joss/geometry/Rect}
becomes Rect. (it's a Type name, not a jsdoc namepath)
- Specify namepaths between braces
- Multiple inheritance
- Using the C3 Method Resolution
Order algorithm, the full
inheritance heirarchy of classes which
@extend
multiple Classes is computed.
- Using the C3 Method Resolution
Order algorithm, the full
inheritance heirarchy of classes which
- Unstyled HTML output
- Module definition for each module
code
andpre
blocks will be processed by highlight-js
- Taglist for each module
- taglists and module definitions are rendered from jade templates (see tasks/tpl)
- Hierarchical menu linking to every module
- Module definition for each module
- Summary information
- List of all declared and external Types, both long names and short names
- List of ambiguous short names (e.g.
joss/geometry/Rect
andjoss/display/Rect
are unique modules, but the last part (the short-name) of both isRect
) - List of undeclared Types (used in parameters, return types, or description namepaths but never declared)
- Percentage of documented variables with markdown descriptions
- Percentage of documented variables with non-empty descriptions
- (Guess) list of direct members of documented classes which have no jsdoc annotations, but probably should (because they're direct members)
amd-doc was created as the documentation generator for the joss framework.