How to document my RequireJs module?

[Pierre Thibault]

Hello,

I am unable to properly document the modules of my project using JsDoc 3. The result is simply catastrophic. I'm using RequiereJs. Here is a sample of my code:

define("sfl/util", function() {
    /**
     * A set for general purpose utilities.
     * @exports sfl/util
     */
    var util = {};
   
    /**
     * @function inherit
     * Set the base type for a new class.
     * This function is useful to set the base class of a new class without
     * having to create an object of the base class to define the class hierarchy.
     * typeName will be added to the prototype of the type so the name of type
     * will accessible on new objects using the "typeName" property.
     * The name of type is also available in the property "name" of "type".
     * @param {Object} type The new class (a function).
     * @param {Object={}} baseType The base type this type inherits.
     * @param {string=} typeName The name of the type.
     */
    function inherit(type, baseType, typeName) {
        baseType = baseType || {};
        if (baseType.prototype) {
            type.prototype = { __proto__: baseType.prototype };
        } else {
            type.prototype = {};
        }
        type.constructor = type;
        if (typeName) {
          //assert(typeof typeName === "string", "typeName is not a string.");
          type.prototype.typeName = typeName;
        }
    };
    util.inherit = inherit;
   
    /**
     * @class Error Class representing an error
     * @property {Error} cause The error that is the cause of this error
     * @property {String} message The error message.
     * @constructor
     * @param {string} message The error message.
     * @param {Error} [cause] The cause of this error.
     * @exports sfl/util
     */
    function Error(message, cause) {
        assert(typeof message === 'string' && message !== '', 'Error: error without a message.');
        assert(cause == undefined || cause instanceof Error,
            'cause can either be undefined or an instance of Error');
        this.message = message;
        this.cause = cause;
    };
    inherit(Error, {}, 'Error');
    util.Error = Error;

    return util;
});

I really like this style. I don't like to put things directly in an object because my functions cannot call one another. So I would like to keep this style but I don't how to make it work with JSDoc and I would appreciate help. Do you know to fix? Is it possible?

Regards.

[Pierre Thibault]

Hello,

I hope someone will read this message at some point. :-)

I change the style of my code so JSDoc can better understand it. But, I don't like that. This is forcing me to write my code a certain way to match the way the tool works. I am adapting my code to the tool instead of having a tool that can adapt to my code. This is not very cool. I also have to use some tricks to make it work.

Here is a code sample that is working better with JSDoc:

define("sfl/util", function() {
    var m = {};

    /**
     * A set for general purpose utilities.
     * @exports sfl/util
     */

    var exports = {
        /**

         * Set the base type for a new class.
         * This function is useful to set the base class of a new class without
         * having to create an object of the base class to define the class hierarchy.
         * typeName will be added to the prototype of the type so the name of type
         * will accessible on new objects using the "typeName" property.
         * The name of type is also available in the property "name" of "type".
         * @param {Object} type The new class (a function).

         * @param {Object} [baseType=Object()] The base type this type inherits.
         * @param {string} [typeName] The name of the type.
         * @returns {Object} The type.
         */
        inherit: m.inherit = function(type, baseType, typeName) {

            baseType = baseType || {};
            if (baseType.prototype) {
                type.prototype = { __proto__: baseType.prototype };
            } else {
                type.prototype = {};
            }
            type.constructor = type;
            if (typeName) {
              //assert(typeof typeName === "string", "typeName is not a string.");
              type.prototype.typeName = typeName;
            }

            return type;
        },

       
        /**
         * @class Error Class representing an error
         * @property {Error} cause The error that is the cause of this error
         * @property {String} message The error message.
         * @constructor
         * @param {string} message The error message.
         * @param {Error} [cause] The cause of this error.

         */
        Error: m.Error = m.inherit(function (message, cause) {

            assert(typeof message === 'string' && message !== '', 'Error: error without a message.');
            assert(cause == undefined || cause instanceof Error,
                'cause can either be undefined or an instance of Error');
            this.message = message;
            this.cause = cause;

        }, {}, 'Error'),
.
.
.

Notice the "m" variable I am using to manage my dependencies. This is the trick I am talking about.

I have problem with this line:

        inherit: m.inherit = function(type, baseType, typeName) {

I have to write:

        inherit: function(type, baseType, typeName) {

so JSDoc can properly parse the code and generate the documentation correctly. Otherwise, it does not properly generate the documentation and I have partial results.

So now I am wondering if it is a good thing to use the use the tool with these constraints. I think I will document the code without generating the documentation at all.

I guess JSDoc is still in development. I hope this feedback will help improve it.

2012/4/10 Pierre Thibault <pierre.t...@gmail.com>

Hello,

I am unable to properly document the modules of my project using JsDoc 3. The result is simply catastrophic. I'm using RequiereJs. Here is a sample of my code:

A+

-------------

Pierre Thibault

Python Developer/Développeur Python
Montréal, QC

pierre.t...@gmail.com

[Jonas Rabbe]

It's been quite a while since the original post, but I was wondering if anyone had come up with better ways of handling RequireJS documentation with JSDoc, for instance using a plugin or similar?

[Daniel Ellis]

I've been using it with requireJS for a good amount of time now. I think in this example, my initial thought would be to take the exports out entirely and define Error as a static property after m is defined:

var m = {

    inherits : function(...) { ... }

};

m.Error = m.inherits(...);

return m;

--
You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jsdoc-users...@googlegroups.com.
To post to this group, send email to jsdoc...@googlegroups.com.
Visit this group at http://groups.google.com/group/jsdoc-users.
For more options, visit https://groups.google.com/groups/opt_out.