How to properly describe events in Backbone views with JSdoc?

Question

I am describing JavaScript code that uses the Backbone framework. I am wondering how to document events that are declared in my views.

Let's say I have a class with this events:

define([], function(Backbone){
  let myView = Backbone.View.extend(
    model: myModel,
    initialize: function() {
        /**
         * @event                  <<- what should I specify here?
         */
        this.model.on('change:foo', function() {
          //do something
        }
    }

    events: {
      'click .btn-next': 'onClickNext',
      'click #finish': 'onClickFinish'
    },

    /**
     * @event                  <<- what should I specify here?
     */
    onClickNext: function() { 
      //do something
    },
    /**
     * @event                  <<- what should I specify here?
     */
    onClickFinish: function() {
       //do something
    }
  );
});

According to JSDoc documentation I should use something like:

/**
 * Description..
 * @event MyView#click
 * @listens MyView#click
 */
onClickNext(){}

But how to specify the class or id of an object that was clicked? And what about event in the model? Should I use @event myModel#change or @event myView#change? And again: how to specify the property that should be changed?

Answer 1

If a method is the listener for an event emitted elsewhere, use @listens, not @event. The class in the ClassName#eventName notation is the class of the emitter of the event.

    initialize: function() {
        /**
         * Anonymous event handler.
         *
         * @listens myModel#change:foo
         */
        this.model.on('change:foo', function() {
          //do something
        }
    }

If a method triggers an event that other methods might listen to, use @fires, not @event.

    /**
     * Do what needs to be done when the user clicks #finish.
     *
     * @event myView#finish
     */
    onClickFinish: function() {
       //do something
       this.trigger('finish', this);
    }

Document the event itself using @event.

       /**
        * Event reporting that the view is finished.
        *
        * @event myView#finish
        * @type {myView}
        */
       this.trigger('finish', this);