How to Use JSDoc @event Tag Correctly?

I am using JSDoc 3.4.2 for my JavaScript API documentation need. By looking at the @event tag example, when I tried to use it, the event name was replaced with “event:” + event name which was a sign that it was looking at the @event tag correctly but found two issues.

1. When I use @fire tag, it would not create a link to the event documentation
2. Event details would be documented in the Global (global.html) page but that page was never generated if the class to be documented is very simple. The link on the top right corner would be broken. If I have a @typedef, it would generate the Global page which would contain the event details but it is a kind of hack.

Solution

So what I found is that I was using the @event tag wrong way. I was using the @event tag within the @class body which was causing both the issues mentioned earlier. Even though, it is not explicitly mentioned in the @event tag documentation, @event tag must be created only after the whole class is fully defined. Then the @event and the @fire tags will work as expected and it will not push the event details to Global page but will keep it in the same class file.

Incorrect way to define @event

/**
* @class
* INCORRECT way to define @event
*/
function PramukhIME() {
    /**
    * Sets the language
    */
    this.setLanguage = function(lang, kb) {
        // function code
    };
    // Following comment is still within the class definition so it will NOT work as expected
    /**
    * Language change event
    * @event PramukhIME#languagechange
    * @type {object}
    * @property {string} language Newly selected language name
    * @property {string} kb Newly selected keyboard name
    */
     
} // class definition ends here

Correct way to define @event

/**
* @class
* CORRECT way to define @event
*/
function PramukhIME() {
    /**
    * Sets the language
    */
    this.setLanguage = function(lang, kb) {
        // function code
    };
} // class definition ends here
 
// Following comment is outside of the class definition so it will work as expected
/**
* Language change event
* @event PramukhIME#languagechange
* @type {object}
* @property {string} language Newly selected language name
* @property {string} kb Newly selected keyboard name
*/