@module, @requires combined with @constructor and @alias, AMD modules

[Sebastian Breuers]

Hello,

I do have the following setup in my code:

/**
 * @module MyModule
 * @requires dependency1
 * @requires dependency2
 */
define([
  'dependency1',
  'dependency2'
],function(dependency1, dependency2){
  'use strict';

  /**
   * @constructor
   * @alias module:MyModule
  var Constructor = function () {
  };

  ConstructorFunction.prototype = /** @lends module:MyModule */{
    /**
     * @function
     */
    somefunc: function () {
      /* using dependecy1 */
    },
    /**
     * @function
     */
    otherfunc: function () {
      /* using dependency2 */
    }
  };

  return Constructor;
});

As soon as I declare @alias module:MyModule the requirements vanish from the documentation page.

If I remove the @alias statement the class is not documented at all.

Could somebody give me a hint, how to adress the issue? I just like to keep the requires section on the documentation page, and have module and class both link to the same page. Is this possible at all?

Thanks in advance and kind regards,

Sebastian

[x...@odoo.com]

I can not help, but if anyone else can I am also interested: also trying to document class-modules, I end up with incorrect (or no links) & formatting as well as fleeting class descriptions and "module:" prefixes littering what little documentation I have.

Here's an example module:

define('me/Foo', ['require'], function (require) {
    'use strict';
    var Class = require('me/Class');

    var Foo = Class.extend({
        init: function () {
        },
        bar: function () {
        }
    });
    return Foo;
});

I attempted to document it thus:

define('me/Foo', ['require'], function (require) {
    'use strict';
    var Class = require('me/Class');

    /**
     * My Foo class
     *
     * @class
     * @extends Class
     * @exports me/Foo
     */
    var Foo = Class.extend(/** @lends Foo.prototype */{
        /**
         * Creates a default Foo
         *
         * @constructs
         */
        init: function () {
        },
        /**
         * Does the thing
         */
        bar: function () {
        }
    });
    return Foo;
});

However it doesn't yield the expected results:

• it documents a separate Foo class and me/Foo module
• the description and @extends are associated with the module, and the latter is not linked to anything, replacing Class by module:me/Class does link but to the module, and the link is prefixed by "module:"
• the system does not seem to understand that Class and me/Class are the same thing (Class is defined similarly to Foo)

Trying to follow the snippets shown in the "AMD Modules" articles made me try this:

/**
 * Foo module/class
 *
 * @module me/Foo
 */
define('me/Foo', ['require'], function (require) {
    'use strict';
    var Class = require('me/Class');

    /**
     * My Foo class
     *
     * @class
     * @extends module:me/Class
     * @alias module:me/Foo
     */
    var Foo = Class.extend(/** @lends Foo.prototype */{
        /**
         * Creates a default Foo
         *
         * @constructs
         */
        init: function () {
        },
        /**
         * Does the thing
         */
        bar: function () {
        }
    });
    return Foo;
});

which actually yields 3 different versions of Foo: 

• a me/Foo module with 2 different "Extends" sections (and links labelled "module:me/Class"), which got the class description but none of the methods and is headered as new module:me/Foo()
  
• a me/Foo class which duplicates the above
• and a Foo class which doesn't get the class description but does get the methods (and their documentations)

Using @lends module:me/Foo.prototype removes the Foo class (me/Foo is still duplicated as identical module and class), but both module:me/Foo are now "duplicated" on their respective pages with the "upper" one having the class description and extends link, and the "lower" one having the methods.

Removing @alias removes the duplication but only keeps the *bottom* section, the inheritance information and class description are lost entirely.

Extending @class to @class module:me/Foo reintroduces the duplication, though with the improvement that the "upper" version gets the "bar" method. It does not get the constructor's documentation which is replaced by the classe's.

Removing the @module removes the "toplevel" duplication of having both a module me/Foo and a class me/Foo with the exact same content, leaving only the class, but the one remaining page still documents module:me/Foo twice slightly differently and is hardly great. The page is also full of module: prefixes (I added @param annotations to the original example to check where and how they ended):

Class: module:me/Foo

module:me/Foo

new module:me/Foo(thing)

My Foo class

Parameters:

Name	Type	Description
thing	integer	wheee

Extends

• module:me/Class

Methods

bar(wheee)

Does the thing

Parameters:

Name	Type	Description
wheee	number	fslhfsdfhj fldsjhfs fldksjhfa

module:me/Foo

new module:me/Foo()

Creates a default Foo

Methods

bar(wheee)

Does the thing

Parameters:

Name	Type	Description
wheee	number	fslhfsdfhj fldsjhfs fldksjhfa

Am I missing things? Is there a way to get a better, more proper result?