Documenting dispatched events

I have questions
1

I've recently deepened in Apache Flex a bit and found out they handle events in a particular way.

The [Event] meta-data in AS3 isn't just for documenting dispatched events at the ASDoc level, but also for allowing MXML components to handle events. (MXML is specific to the Flex technology which evaluated in Flash or AIR.)

Are there any plans on allowing ECMAScript to use arbitrary, character meta-data as in ECMAScript 4?

2

The language doesn’t have events. Can you elaborate on what you’re asking?

3

I was considering that the JSDoc tool supports @event tags used to document dispatched events in usual event cycles such as DOM events and Display List events.

I thought it'd be allowed to discuss these here, even though this is a ECMAScript community.

4

Could you show an example? I'm not sure what "character meta-data" refers to. Thanks!

5

Right

In ActionScript 3, meta data attached to annotatable directives such as class definitions or variable definitions are simply repeatable (not unique), key-value entries, where the key is optional and is an Identifier, and the value is a String literal or, if the entry is keyless, the value may appear solely as an Identifier translating to a String.

ES4 examples:

[M1]
[M1(x = "y", y = "z")]
[M1("y")]
[M1(y)]
var x

There is no static typing involved in meta-data; the ES4 compilers each may have different behavior when processing them.

In the case of documenting events, the [Event] meta-data in Apache Flex looks as follows, considering an EventDispatcher:

package com.example.demo {
    import flash.events.*;

    /**
     * @eventType DoorEvent.ENTER
     */
    [Event(name = "enter", type = "DoorEvent")]
    /**
     * @eventType DoorEvent.EXIT
     */
    [Event(name = "exit", type = "DoorEvent")]
    /**
     * Comment.
     */
    public class Center extends EventDispatcher {
    }
}

As you can see, meta-data may repeat (they are not unique) and certain meta-data may be preceded by an ASDoc comment (for example, for Apache Flex, [Event]), while any other compiler unrecognized meta-data propagates the preceding ASDoc comment to the annotatable directive (the class, or the variable, for example).

6

Thank you. Have you looked into: GitHub - tc39/proposal-decorator-metadata ?

1 Like
7

Interesting, I wasn't aware of this one. It seems to be a proposal intended for runtime inspection. I guess compilers about TypeScript are able to detect current decorators ahead of time and associate them as meta-data for influencing the program's AOT compilation.

I don't think TypeDoc comments were ever applied to decorators in TypeScript, or JSDoc comments applied to decorators in JavaScript. If this is not possible, I guess the meta-data decorator would need additional entries, along the lines of:

@Event({
    name: "enter",
    type: DoorEvent,
    constant: DoorEvent.ENTER,
    description: "Dispatched when",
})
class Center {}

You see, I didn't find it very readable. At the other hand, JSDoc and TypeDoc are diverging: TypeDoc supports the @event tag for a different purpose and doesn't treat it the same way.

Another thing to add is that using the Event name above for the decorator may cause name conflict between an imported Event class and an Event decorator. :(

8

This is still sucking a lot for me since I don't use reactive models.