Can't get @event to work well with overloads

[PanayotCankov]

I think the ultimate solution would work well for .d.ts-es like:

declare module "background-http" {
    /**
     * Encapsulates some information for background http transfers.
     */
    export interface Task {

        /**
         * Subscribe for a general event by name.
         * @param event The name of the event to subscribe for.
         * @param The handler called when the event occure.
         */
        on(event: string, handler: (e: observable.EventData) => void): void;

        /**
         * Subscribe for error notifications.
         * @param event The name of the event to subscribe for.
         * @param handler A handler that will receive the error details
         */
        on(event: "error", handler: (e: ErrorEventData) => void): void;

        /**
         * Subscribe for progress notifications.
         * @param event The name of the event to subscribe for.
         * @param handler A handler that will receive a progress event with the current and expected total bytes 
         */
        on(event: "progress", handler: (e: ProgressEventData) => void): void;

        /**
         * Subscribe for success notification.
         * @param event The name of the event to subscribe for.
         * @param handler A function that will be called with general event data upon successful completion
         */
        on(event: "complete", handler: (e: observable.EventData) => void): void;
    }
}

Replacing the @param with @event fails the code completion and suggestions for parameters in some IDEs. Using @event somewhere would be fine (though it would appear as plain text in the suggestions but the same is valid for @return) I would be more comfortable setting the "on" and "addEventListener" names as parameters to the tool rather than adjusting my .d.ts-es.

Currently the oversloads for the above methods are displayed nicely, but when the @event is used instead of @param for the first paramter, all parameter documentation display the doc from the first overload declaration. I guess I am doing something wrong?

It would be nice if this could be added in the documentation.

[PanayotCankov]

TypeScript decorators can also be considered to mark events.

[sebastian-lenz]

Hi Panayot, the @event param is intended to be used additionally to any other doc tags, something like this:

/**
 * Subscribe for a general event by name.
 * @param event The name of the event to subscribe for.
 * @param The handler called when the event occure.
 * @event
 */
on(event: string, handler: (e: observable.EventData) => void): void;

As events are not part of the TypeScript language the @event tag should just give a slightly hint in the documentation. It can be used in conjunction with any code element, e.g. in TypeDoc we use the @event tag with static variables.

[PanayotCankov]

Could you check the docs for this nativescript plugin:
Task#on
All of the overloads show the same argument description for the "handler" property:
A handler that will receive the error details

I tried to use the same documentation without the @event and then it works fine, but ofc. then the on is not placed in the events section.

[sebastian-lenz]

Okay, that's a bug, the parameter descriptions are resolved incorrectly if the flag @event is set. I've included a fix to correct that.

[cancerberoSgx]

Not 100% percent related with the issue but I've just documented a couple of alternatives to describe/document events with TypeDoc that I think could help you. also I would very appreciate if you could review it or give feedback:

https://cancerberosgx.github.io/javascript-documentation-examples/examples/typedoc-tutorial-basic/docs/docco/src/index.html#events

Thanks