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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
$data.Class.define("TheClass", null, null, { simpleField: 42, constructor: function (p1, callback) { /// <description> /// The full description of the class, can contains /// HTML formatting with [b]BBCode[/b]. /// </description> /// /// <param name="p1" type="int">Free [i]text[/i]</param> /// <param name="callback" type="Function" optional="true"> /// <param name="sender" type="object" /> /// <param name="nameOnly" /> /// </param> /// /// <field name="simpleField" type="int">Simple field with static definition</field> /// <field name="property" type="int">Property, defined in constructor</field> Object.defineProperty(this, "property", { value: 24, writable: false }); }, _simpleFunction: function (arg) { /// <summary>Simple function definition, seems to be private, but it is a jsdoc parameter</summary> /// <param name="arg">Just like constructor parameter descriptions</param> /// <returns type="returnType">Describe return value here</returns> }, overloadedFunction: function() { /// <signature> /// <summary>The signature tag must contains a valid function documentation</summary> /// </signature> /// /// <signature> /// <summary>You can add any number of signature blocks</summary> /// </signature> } }); |
The generated file:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 |
$data.Class.define("TheClass", null, null, /** @lends TheClass.prototype */ { /** Simple field with static definition @name TheClass.prototype.simpleField @type int */ simpleField: 42, /** @extends $data.Base @class The full description of the class, can contains HTML formatting with <strong class="bbcode-bold">BBCode</strong>. @constructs @property {int} property Property, defined in constructor @param {int} p1 Free <em class="bbcode-italic">text</em> @param {function(object sender, nameOnly)} [callback] write description here */ constructor: function (p1, callback) { Object.defineProperty(this, "property", { value: 24, writable: false }); }, /** Simple function definition, seems to be private, but it is a jsdoc parameter @name TheClass.prototype._simpleFunction @function @param arg Just like constructor parameter descriptions @returns {returnType} Describe return value here */ _simpleFunction: function (arg) { }, /** The signature tag must contains a valid function documentation @name TheClass.prototype.overloadedFunction @function */ /** You can add any number of signature blocks @name TheClass.prototype.overloadedFunction^2 @function */ overloadedFunction: function () { } }); |
Download
Available at http://vsdoc2jsdoc.codeplex.com (soon)
