YARD for JavaScript
A YARD plugin that adds support for documenting JavaScript source files with minimal amount of manual declarations, support for YARD syntax, and templates for displaying HTML documentation.
The plugin relies on certain conventional syntaxes for declaring classes and mixins. See the "Generating documentation" section below for how to customize this.
Documenting with yard-js
Documenting with yard-js
should be similar to documenting with YARD.
Information on how to document with YARD can be found in YARD's
Getting Started Guide.
Just like in Ruby, you will document methods or classes by adding docstrings
above the definition. Unlike jsdoc, you do not need to explicitly denote the
class name or details, as these will be automatically detected by YARD. For
instance, the following File class can be documented like so:
/**
* This class represents files on disk.
*
* @see FileSystem
*/
inherit(IO, {
/**
* Opens a new file at the location of `filename`
*
* @param filename [String] the location on disk of the file to open.
* @param access [String] a combination or 'r' and 'w' for access modes.
*/
constructor: function (filename, access) { ... },
/**
* Reads from the open file
*
* @param numBytes [number] the number of bytes to read. Leave this
* empty to read all remaining data.
* @return [Buffer] the data read from disk as a buffer.
*/
read: function (numBytes) { ... }
});
All macros and tags available
in YARD are available in yard-js
.
Requirements
YARD for JavaScript relies on the following software:
Note that installing Ruby is not covered in the installation section.
Installing
To install, clone the repository and bundle install
to install dependencies:
$ git clone git://github.com/lsegal/yard-js
$ cd yard-js
$ bundle install
Usage
To generate documentation for a project, change into the project directory and type:
$ bundle exec yard -m markdown -e /path/to/yard-js/lib/yard-js.rb
To take advantage of class detection you will also need to customize the
expressions used by yard-js
to find class definitions. These are done through
the following command line arguments:
--define-class-expr
: The syntax used in your code to define a class. For
example, --define-class-expr inherit
will look for the following statement:
inherit(SuperClass, {
// class implementation
constructor: function() { /* constructor function */ },
foo: function() { /* an instance method */ }
});
--update-class-expr
: The syntax used in your code to update the class object
itself (also known as class level methods/properties). For example,
--update-class-expr update
will detect the following block as a set of class
methods:
update(MyClass, {
bar: function() { /* a method only available as MyClass.bar() */ }
});
--mixin-module-expr
: The syntax used to detect modules mixed into a class.
For example, --mixin-module-expr mixin
will detect:
mixin(MyClass, SomeMixin);
To simplify setting these values, you can add these command line arguments
to a .yardopts
file in the root level of your project, for example:
--define-class-expr inherit
--update-class-expr update
--mixin-module-expr mixin
Note that by default YARD uses RDoc comment formatting. This is overridden in
the above example by adding -m markdown
to use markdown formatting for
documentation comments.
Known Issues
This plugin is currently not a true "plugin". This will require availability as a RubyGem, which will happen soon.
This plugin is currently not compatible with the YARD server architecture. This is being worked on.
This plugin cannot document Ruby code alongside JavaScript code due to the way it modifies YARD internals. Making yard-js work side-by-side Ruby code will be a long-term goal.
License
yard-js
is available under the MIT license.