Codo is a CoffeeScript API documentation generator, similar to YARD. Its generated documentation is focused on CoffeeScript class syntax for classical inheritance and not for JavaScript's prototypal inheritance.
- Detects classes, methods, constants, mixins & concerns.
- Many tags to add semantics to your code.
- Generates a nice site to browse your code documentation in various ways.
Annotate your source with Codo tags to add semantic information to your code. It looks like this:
# Base class for all animals.
#
# @example How to subclass an animal
# class Lion extends Animal
# move: (direction, speed): ->
#
class Example.Animal
# The Answer to the Ultimate Question of Life, the Universe, and Everything
@ANSWER = 42
# Construct a new animal.
#
# @param [String] name the name of the animal
# @param [Date] birthDate when the animal was born
#
constructor: (@name, @birthDate = new Date()) ->
# Move the animal.
#
# @example Move an animal
# new Lion('Simba').move('south', 12)
#
# @param [Object] options the moving options
# @option options [String] direction the moving direction
# @option options [Number] speed the speed in mph
#
move: (options = {}) ->Then generate the documentation with the codo command line tool. You can browse the
generated Codo documentation to get a feeling how you can navigate in various
ways through your code layers.
In the Example namespace you'll find some classes and mixins that makes absolutely no sense, its purpose is only to
show the many features Code offers. In addition, there's a list of
Codo generated documentations
in the wiki. Please add your project if you're using Codo. Thanks!
Codo is available in NPM and can be installed with:
$ npm install -g codoPlease have a look at the CHANGELOG when upgrading to a
newer Codo version with npm update.
You have to annotate your code with Codo tags to give it some meaning to the parser that generates the documentation.
Each tag starts with the @ sign followed by the tag name. See the following overview for a minimal description of all
available tags. Most tags are self-explaining and the one that aren't are described afterwards in more detail.
Tags can take multiple lines, just indent subsequent lines by two spaces. It's also possible to use CoffeeScript block comments instead of the normal comments.
The following table shows the list of all available tags in alphabetical order with its expected options. An option in parenthesis is optional and the square brackets are part of the Codo tag format and must actually be written. Some tags can be defined multiple times and they can be applied to different contexts, either in the comment for a class, a comment for a mixin or in a method comment.
| Tag format | Multiple occurrences | Classes | Mixins | Methods |
| @abstract (message) | ✔ | ✔ | ✔ | |
| @author name | ✔ | ✔ | ✔ | ✔ |
| @concern mixin | ✔ | ✔ | ||
| @copyright name | ✔ | ✔ | ✔ | |
| @deprecated | ✔ | ✔ | ✔ | |
| @example (title) Code |
✔ | ✔ | ✔ | ✔ |
| @extend mixin | ✔ | ✔ | ||
| @include mixin | ✔ | ✔ | ||
| @note message | ✔ | ✔ | ✔ | ✔ |
| @method signature Method tags |
✔ | ✔ | ||
| @mixin version | ✔ | |||
| @option option [type] name description | ✔ | ✔ | ||
| @overload signature Method tags |
✔ | ✔ | ||
|
@param [type] name description @param name [type] description |
✔ | ✔ | ||
| @private | ✔ | ✔ | ✔ | |
| @return [type] description | ✔ | |||
| @see link/reference | ✔ | ✔ | ✔ | ✔ |
| @since version | ✔ | ✔ | ✔ | |
| @todo message | ✔ | ✔ | ✔ | ✔ |
| @version version | ✔ | ✔ | ✔ |
There are two different format recognized for your parameters, so you can chose your favorite. This one is with the parameter after the parameter type:
# Feed the animal
#
# @param [World.Food] food the food to eat
#
feed: (food) ->And this one with the name before the type:
# Feed the animal
#
# @param food [World.Food] the food to eat
#
feed: (food) ->If you have an object as parameter and you like to defined the accepted properties as options to the method, you can
use the @options tag:
# Feed the animal
#
# @param [Object] options the calculation options
# @option options [Integer] age the age of the animal
# @option options [Integer] weight the weight of the animal
#
expectationOfLife: (options) ->The first parameter to the option tag is the parameter name it describes, followed by the parameter type, name and description.
The object types for the @param, @option and @return tags are parsed for known classes or mixins and linked. You
can also define types for Arrays with:
#
# @param [World.Region] region the region of the herd
# @return [Array<Animals>] the animals in the herd
#
getHerdMembers: (regions) ->If you allow your method to take different parameters, you can describe the method overloading with the @overload tag:
# This is a generic Store set method.
#
# @overload set(key, value)
# Sets a value on key
# @param [Symbol] key describe key param
# @param [Object] value describe value param
#
# @overload set(value)
# Sets a value on the default key `:foo`
# @param [Object] value describe value param
# @return [Boolean] true when success
#
set: (args...) ->The @overload tag must be followed by the alternative method signature that will appear in the documentation, followed
by any method tag indented by two spaces.
If you copy over functions from other objects without using mixins or concerns, you can add documentation for this
virtual (or dynamic) method with the @method tag:
# This class has a virtual method, that doesn't
# exist in the source but appears in the documentation.
#
# @method #set(key, value)
# Sets a value on key
# @param [Symbol] key describe key param
# @param [Object] value describe value param
#
class VirtualMethodsThe @method tag must be followed by the method signature that will appear in the documentation, followed
by any method tag indented by two spaces. The difference to the @overload tag beside the different context is that
the signature should contain either the instance prefix # or the class prefix ..
It's common practice to mix in objects to share common logic when inheritance is not suited. You can read more about mixins in the The Little Book on CoffeeScript.
Simply mark any plain CoffeeScript object with the @mixin tag to have a mixin page generated that supports many tags:
# Speed calculation for animal.
#
# @mixin
# @author Rockstar Ninja
#
Example.Animal.Speed =
# Get the distance the animal will put back in a certain time.
#
# @param [Integer] time Number of seconds
# @return [Integer] The distance in miles
#
distance: (time) ->Next mark the target object that includes one or multiple mixins:
# @include Example.Animal.Speed
class Example.Animal.Lionand you'll see the mixin methods appear as instance methods in the lion class documentation. You can also extend a mixin:
# @extend Example.Animal.Speed
class Example.Animal.Lionso its methods will show up as class methods.
A concern is a combination of two mixins, one for instance methods and the other for class methods and it's
automatically detected when a mixin has both a ClassMethods and an InstanceMethods property:
# Speed calculations for animal.
#
# @mixin
# @author Rockstar Ninja
#
Example.Animal.Speed =
InstanceMethods:
# Get the distance the animal will put back in a certain time.
#
# @param [Integer] time Number of seconds
# @return [Integer] The distance in miles
#
distance: (time) ->
ClassMethods:
# Get the common speed of the animal in MPH.
#
# @param [Integer] age The age of the animal
# @return [Integer] The speed in MPH
#
speed: (age) ->You can use @concern to include and extend the correspondent properties:
# @concern Example.Animal.Speed
class Example.Animal.LionCodo comments and extra files written in Markdown syntax are rendered as GitHub Flavored Markdown.
Codo comments and all tag texts will be parsed for references to other classes, methods and mixins and are automatically linked.
There are several ways of link types supported and all can take an optional label after the link.
- Normal URL links:
{http://coffeescript.org/}or{http://coffeescript.org/ Try CoffeeScript} - Link to a class or mixin:
{Animal.Lion}or{Animal.Lion The might lion} - Direct link to an instance method:
{Animal.Lion#walk}or{Animal.Lion#walk The lion walks} - Direct link to a class method:
{Animal.Lion.constructor}or{Animal.Lion.constructor} A new king was born
If you are referring to a method within the same class, you can omit the class name: {#walk}.
The @see tag supports the same link types, just without the curly braces:
@see http://en.wikipedia.org/wiki/Lion The wikipedia page about lionsAfter the installation you will have a codo binary that can be used to generate the documentation recursively for all
CoffeeScript files within a directory.
$ codo --help
Usage: codo [options] [source_files [- extra_files]]
Options:
-r, --readme The readme file used [default: "README.md"]
-q, --quiet Show no warnings [boolean] [default: false]
-o, --output-dir The output directory [default: "./doc"]
-v, --verbose Show parsing errors [boolean] [default: false]
-h, --help Show the help
-s, --server Start a documentation server
--private Show private methods and classes
--title [default: "CoffeeScript API Documentation"]You can define your project defaults by write your command line options to a .codoopts file:
--readme README.md
--title "Codo Documentation"
--private
--quiet
--output-dir ./doc
./src
-
LICENSE
CHANGELOG.mdPut each option flag on a separate line, followed by the source directories or files, and optionally any extra file that
should be included into the documentation separated by a dash (-). If your extra file has the extension .md, it'll
be rendered as Markdown.
You can quickly search and jump through the documentation by using the fuzzy finder dialgo:
- Open fuzzy finder dialog:
Ctrl-T
In frame mode you can toggle the list naviation frame on the left side:
- Toggle list view:
Ctrl-L
You can focus a list in frame mode or toggle a tab in frameless mode:
- Class list:
Ctrl-C - Mixin list:
Ctrl-I - Method list:
Ctrl-M - File list:
Ctrl-F
You can focus and blur the search input:
- Focus search input:
Ctrl-S - Blur search inputL
Esc
In frameless mode you can close the list tab:
- Close list tab:
Esc
Issues hosted at GitHub Issues.
The Codo specs are template based, so make sure you provide a code snippet that can be added as failing spec to the project when reporting an issue with parsing your CoffeeScript code.
You can check if some parsing errors have occurred by running Codo in verbose mode.
Source hosted at GitHub.
Pull requests are very welcome! Please try to follow these simple rules if applicable:
- Please create a topic branch for every separate change you make.
- Make sure your patches are well tested.
- Update the documentation.
- Update the README.
- Update the CHANGELOG for noteworthy changes.
- Please do not change the version number.
- Jeremy Ashkenas for CoffeeScript, that mighty language that compiles to JavaScript and makes me enjoy JavaScript development.
- Loren Segal for creating YARD and giving me the perfect documentation syntax for dynamic programming languages.
- Stratus Editor for open sourcing their fuzzy filter.
- Docco is a quick-and-dirty, literate-programming-style documentation generator.
- CoffeeDoc an alternative API documentation generator for CoffeeScript.
- JsDoc an automatic documentation generator for JavaScript.
- Dox JavaScript documentation generator for node using markdown and jsdoc.
(The MIT License)
Copyright (c) 2012 Michael Kessler
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.