/*
https://groups.google.com/forum/#!topic/jsdoc-users/izErstbwNUU

I advocate the use of already-defined patterns.
A bunch of new tags is not the main aim of my proposition.

Please find below JS code with comments.
It is self descriptive example.
-- Tawez
*/


/**
 * @namespace
 */
Ns = {
        /**
         * Nested structures could be documented in simple way,
         * we just need to reuse already defined patterns.
         * Property dot notation (http://code.google.com/p/jsdoc-toolkit/wiki/
TagParam#Parameters_With_Properties) works,
         * but output is flat and we lose information about property
structure.
         * Michael asked about view. IMHO it should be rendered as in
following example (simplified markdown like syntax to illustrate the
idea):
         * @example
         * - Object staticDeepStruct
         *   Comments etc.
         *   - Number i
         *     Positive val
         *   - String s
         *     String var
         * @type Object
         */
        staticDeepStruct: {
                /**
                 * Positive val
                 * @type Number
                 * @default 1
                 */
                i: 1,

                /**
                 * String var
                 * @type Number
                 * @default "text"
                 */
                s: "text",
        }
};


/*
-----------------------------------------------------------------------
 * This comment block should give following documentation for
constructor:
 * Class Detail
 * Ns.Base(config)
 * +-------+
 * |example|
 * +-------+
 * +-------+
 * |example|
 * +-------+
 *
 * Parameters:
 *     {Object} config Optional
 *         Config object
 *         - {String} text
 *           Value for text property
 *
-----------------------------------------------------------------------
 */

/**
 * @class
 * @example
 * var b = new Ns.Base();
 * @example
 * var b = new Ns.Base({
 *         text: "new value"
 *     });
 * @param {Object} [config] Config object
 * @param {String} config.text Value for text property
 */
Ns.Base = createClass(Object, /** @lends Ns.Base.prototype */ {
        /**
         * @type String
         * @default "make some noise"
         */
        text: "make some noise",

        /**
         * deepStruct should be rendered in the same way as
Ns.staticDeepStruct
         * @type Object
         */
        deepStruct: {
                /**
                 * Positive val
                 * @type Number
                 * @default 111
                 */
                i: 111,

                /**
                 * String var
                 * @type Number
                 * @default "more text"
                 */
                s: "more text",
        },

        /**
         * Returns text property value
         * @returns {String}
         */
        foo: function () {
                return this.text;
        }

        /**
         * If we have "directive" lends, then tag memberOf is unnecessary
here - we have well defined "context"
         * @function
         * @name bar
         * @memberOf Ns.Base.prototype
         * @returns Number
         */
});


/**
 * @class
 * @augments Ns.Base
 * @property {Number} [i=1]
 * Some comments to i property
 * @example
 * // this is an example for i property,
 * // but will be parsed and rendered as constructor example, arghhhh!
 * @property {String} [s=""]
 * Some comments to s property
 */
Ns.Derived = createClass(Ns.Base, /** @lends Ns.Derived.prototype */ {
        /**
         * As far as I know this is the only working pattern
         * if I'd like to redefine property documentation with a lot of text
and examples
         * and without providing the code of property.
         * BTW If we have "directive" lends, then tag fieldOf is unnecessary
here - we have well defined "context"
         * @example
         * // this is an example for text property,
         * // and will be rendered in the right place
         * @name text
         * @fieldOf Ns.Derived.prototype
         * @type String
         * @default "be quiet"
         */


        /**
         * Dot notation works but right now function gets wrong definition as
<tt>{Object<u>, number,
         number</u>} foo()</tt> (I think it is technical problem only).
         * As an alternative we can use colon notation as below.
         * Should be rendered in the same way as Ns.staticDeepStruct
         * @returns {Object} The coordinates of the current target
         * @returns {number} return:x The x value.
         * @returns {number} return:y The y value.
         */
        foo: function () {
                return {
                        x: 0,
                        y: 0
                };
        }

});