CoffeeScript API Documentation Generation
We all forget, eventually, the classes, methods, and variables we created years, months, and sometimes just days before. This results in expended time and effort to track down where exactly something is being invoked or from where it is inherited. Compounding this is the, potentially steep, learning curve of anyone new to the group. There is also the risk of losing much of the tribal knowledge in the history of a project.
In an attempt to limit the impact of the above, you probably should begin documenting the classes and methods and variables within your CoffeeScript files. There are several generation tools, but considering your current state and structure, some options prevail above the others.
Drawbacks in both cases is that there will need to be time devoted, at least initially, to the documentation and attention to the documentation standard during review, and also a shift in some naming conventions to fully take advantage of the generation.
CoffeeDoc [usage]
+ similar to Python docstrings
+ single line comment possible
+ can use markdown syntax
+ simple to begin using
+ npm package
+ themeable (sorta)
- only processes class and methods
- default theme is not easily navigable
- would require additional time to theme
- inner linking is a priori and must be done manually
- lacking extend documentation of how to use
- no parsing error indication
Codo [usage]
+ documents all variables and methods
+ can use markdown syntax
+ more customizable at command line
+ easily run from build tool, ie. Grunt
+ can have an options file in the project root
+ javadoc style generated documentation
+ keyboard navigation in generated docs
+ more verbose documentation standard
+ automatic linking and simple inner linking
+ specialized tags to add meaning
+ npm package
- more verbose documentation standard (for full benefit)
- specialized tags (a little more to learn)
- change to some naming conventions (for full benefit); eg. extended classes
- unfamiliar documentation standard (for some people)
- all the above means more time to finish initial effort
- javadoc style generated documentation, ie. frames used
- claims to be themeable, but can not determine how
- parsing error indication cryptic
Docco [usage]
+ literate CoffeeScript
+ ‘natural’ commenting style
+ code comments retained
+ fast and easy to use
+ can use markdown syntax
+ themeable; ie. can specify custom css and jst template
+ base for coffedoc and codo (and others)
+ npm package
- literate CoffeeScript (is a little foreign to normal source code)
- non recursive (without a wrapper script)
- flat output (without wrapper script)
- would require additional time to theme
- inner linking not automatic
- no parsing error indication
- easy to mixup code and comments (by design since is in literate style)
- examples and extend documentation are hard to come by
- Install via npm: `> sudo npm install -g [coffeedoc | codo | docco]`
- Run each on your project files:
specifying `-o /tmp/[coffeedoc | codo | docco]` if desired. - Open each index.html in a browser to compare side by side.
The above evaluations are based upon the projects on which I am currently looking to implement the generation. I, personally, prefer the use of Codo because of it’s verbosity and out of the box theme. However, it may be too much for smaller projects or ones with a simpler structure to its source files.