JSDoc

General syntax

To have a good view of the JSDoc syntax you can have a look to the official JSDoc documentation.

Dana’s syntax and best practice

The following example illustrates the specifics due to the OOP syntax enforced by the framework :

import $MySuperClass from "@MySuperClass";

/**
 * A description of the class, what it does, usage, examples, ...
 *
 * @example
 * var great = new MyGreatClass({name: "great", flag: true});
 * great.publicMethod("param1", great);
 *
 * @name MyGreatClass
 * @class
 * @extends MySuperClass
 *
 * @property {string} name - The name of ...
 * @property {boolean} flag - A flag to ...
 */
export default $MySuperClass.declare("MyGreatClass", {

    properties: /** @lends MyGreatClass.prototype */ {
        name: null,
        flag: false
    },

    statics: /** @lends MyGreatClass */ {
        /**
         * Description of the constant.
         * @const
         * @type {number}
         * @default 1
         */
        CONST_1 : 1,

        /**
         * Description of the static method.
         * @returns {number} Returns ...
         * @static
         */
        staticMethod : function(){
            return this.CONST_1;
        },

        /**
         * Triggered when ...
         *
         * @event MyGreatClass#event
         * @param {Object} data ...
         */
        "event": "great.event"
    },

 /**
  * @private
  */
 constructor : function(){},

    methods:  /** @lends MyGreatClass.prototype */ {
        /**
         * Description of the method.

         * @param {string} param1 The first parameter.
         * @param {object} param2 The second parameter.
         * @returns {boolean} Returns true if ..., else false.
         * @fires MyGreatClass#event
         */
        publicMethod : function(param1, param2) {},

        /**
         * Description of the method.
         * @param {string} param1 The first parameter.
         * @param {object} param2 The second parameter.
         * @returns {boolean} Returns true if ..., else false.
         * @protected
         */
        _protectedMethod : function(param1, param2) {},

        /**
         * Description of the method.
         * @param {string} param1 The first parameter.
         * @param {object} param2 The second parameter.
         * @returns {boolean} Returns true if ..., else false.
         * @private
         */
        __privateMethod : function(param1, param2) {},

        /**
         * Override superclass method.
         * @override
         */
        _overriddenMethod : function() {},

         /**
          * @abstract
          */
        _abstractMethod : function() {}

        /**
         * @override
         */
        _implementationMethod : function() {}
    }
});