AMD modules and events

[turboteddy]

I would be very thankful if you could provide an example in documentation on how to document events in the context of AMD modules (including the tags @event, @fires and @listens). Have tried numerous of combinations of syntax, but no result as expected... Hard to get my head around this one. E.g., what is the best way to document something like this?

/** @module a/b/c */
define(['dep1', 'dep2'], function (dep1, dep2) {
    return declare([...], {

       /**
         * This is the event handler
         * @listens event:eventname
         */
       myEventListener : function (event) {

       },

       /**
        * This is the description of the event 
        * @event description. 
        * @name a/b/c#event:eventname
        */
    };
});

...in combination with:

/** @module a/b/d */
define(['dep3', 'dep4'], function (dep3, dep4) {
    return declare([...], {

     /**
     * This function fires the event. 
     * @fires module:a/b/c#event:eventname
     */
     onSomething:function () {
        this.emit(eventname, {
             ...
        });
     }

    };
});

Any feedback / documentation would be highly appreciated!

[patocallaghan]

Did you manage to get this working? I'm having a similar issue.

[turboteddy]

nope, @patocallaghan, I gave up. Hope this will become part of the documentation soon.

[micmath]

Using some of the examples in the unit test fixtures, I came up with the example below as an illustration. Is this useful?

/**
    Some description of the playground/monitor module.
    @module playground/monitor
 */
define('playground/monitor', [], function () {
    var exports = {
        /**
            @method module:playground/monitor.reportThrowage
            @listens module:hurler#snowball
         */
        reportThrowage: function (e) {
            this.log('snowball thrown: velocity ' + e.velocity);
        }
    };

    return exports;
});


/**
    Some description of the hurler module.
    @module hurler
 */
define('hurler', [], function () {
    /**
        Some description of snowball events.
        @event module:hurler#snowball
        @property {number} velocity
    */

    var exports = {
        /**
            @method module:hurler.attack
            @fires module:hurler#snowball
         */
        attack: function (e) {
            this.emit('snowball', { velocity: 10 });
        }
    };

    return exports;
});

[patocallaghan]

Thanks @micmath, It's kind of working now but I'll just have to rework some of my comments to make it work properly. Thanks for the tip about the tests.

@turboteddy have a look here and you may be able to reverse-engineer how the events work...

[hegemonic]

Added to the @event page on Use JSDoc. I'll move part of the example to the new @listens page when I address jsdoc/jsdoc.github.io#25.