Documenting Node.js projects [closed]

Solution 1:

JSDoc is a port of JavaDoc. So basically the documentation assumes classical OOP and that's not suited to JavaScript.

Personally I would recommend using docco to annotate your source code. Examples of it can be found for underscore, backbone, docco.

A good alternative to docco is groc

As for an actual API documentation, I personally find auto generated documentation from comments just does not work for JavaScript and recommend you hand-write your API documentation.

Examples would be underscore API, Express API, nodejs API, socket.io docs

Similar StackOverFlow questions

• Generating Javascript documentation

Solution 2:

YUIDoc is a Node.js application that generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen. YUIDoc provides:

• Live previews. YUIDoc includes a standalone doc server, making it trivial to preview your docs as you write.
• Modern markup. YUIDoc's generated documentation is an attractive, functional web application with real URLs and graceful fallbacks for spiders and other agents that can't run JavaScript.
• Wide language support. YUIDoc was originally designed for the YUI project, but it is not tied to any particular library or programming language. You can use it with any language that supports /* */ comment blocks.

Solution 3:

NOTE: Dox no longer outputs HTML, but a blob of JSON describing the parsed code. This means the code below doesn't work terribly well any more...

We ended up using Dox for now. It is a lot like docco, that Raynos mentions, but thows all of it in one bit HTML-file for output.

We hacked this into our makefiles:

JS_FILES := $(shell find lib/ -type f -name \*.js | grep -v 3rdparty)

#Add node_modules/*/bin/ to path:
#Ugly 'subst' hack: Check the Make Manual section 8.1 - Function Call Syntax
NPM_BINS:=$(subst bin node,bin:node,$(shell find node_modules/ -name bin -type d))
ifneq ($(NPM_BINS),) 
    PATH:=${NPM_BINS}:${PATH}
endif

.PHONY: doc lint test

doc: doc/index.html

doc/index.html: $(JS_FILES)
    @mkdir -p doc
    dox --title "Project Name" $^ > $@

It is not the prettiest or most efficient documentation ever made (and dox has quite a few minor bugs) - but I find it work rather well, at least for minor projects.