JayData.org

How do we generate the API docs?

Author: Janos Roden June 1st, 2012


The documentation has two main requirements:

  • It has to work with the Visual Studio IntelliSense while developing JayData
  • The build process must be able to generate a HTML output

VS11 supports the classic /// code comment in JavaScript, but there is no tool, which produces a HTML documentation  from these comments, or exports into a generic format.

The most popular tool for creating JavaScript API documentation is the jsdoc-toolkit, that uses different syntax and tags, which do not always have a VS11 equivalent. The most important difference is, that VSDoc uses XML comments inside the blocks, while jsdoc expects them before the block in @tag format.

As a solution, we developed our own tool, that reads the JayData source files, and converts its VSDoc comments into proper jsdoc format. The advantage is, when there is no equivalent matchup, we can use custom markup, e.g: documenting a class is done by using the <description> tag in the class constructor.

VSDoc2JsDoc features

  • BBCode is usable in texts, so we don’t need to deal with HTML escaping, which would be needed because of embedding into XML format.
  • Recognizes JayData class definitions: $C, $data.Class.define, $data.Class.defineEx, baseClass.extend.
  • Signature can be added to function parameters.

Example

The original file:

The generated file:

Download

Available at http://vsdoc2jsdoc.codeplex.com (soon)