Project Description

The goal of this project is to convert VSDoc JavaScript comments of JayData classes to JSDoc comment format. Using this tool you can generate the API reference of your JayData components and keep your JavaScript documentation up-to-date.

Features

  • BBCode support, 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.
  • The output of this tool can be used to generate HTML documentation (using jsdoc-toolkit)

Command line options

  • -i, --index The path of the XML file, which enlists the files to process. Ex.: JayData_index.xml
  • -p, --projectDir input project folder path (file paths in index file must be relative to this folder)
  • -o, --output target folder path
  • -c, --config desired output config file path of generated for jsdoc-toolkit

Example to run the tool
Vsdoc2jsdoc.exe --projectDir C:\JayData --index  C:\JayData\JayData_Index.xml --config  C:\JayData\apidoc\jsdoc.config --output  C:\JayData\apidoc\js 


Check out one example output
http://jaydata.org/blog/how-do-we-generate-the-api-docs

Input

$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>
    }
});

Output

$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&nbsp;sender,&nbsp;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 () {

    }
});

Note

  • VSDoc2JSDoc tool doesn't process the comments of standard JavaScript function declarations, it works only with JayData classes

Last edited Jun 4, 2012 at 1:32 PM by JayDataOrg, version 11