Question

Lets say my class X is able to dispatch 3 types of (custom) events.
Where and how should I best document this behaviour within my class file?

Answer 1

Add the [Event] meta tag above your class.

Example from Starling Framework:

package starling.core
{

    /** Dispatched when a new render context is created. */
    [Event(name="context3DCreate", type="starling.events.Event")]

    /** Dispatched when the root class has been created. */
    [Event(name="rootCreated", type="starling.events.Event")]

    /** The Starling class represents the core of the Starling framework.
     *
     *  <p>The Starling framework makes it possible to create 2D applications and games that make
     *  use of the Stage3D architecture introduced in Flash Player 11. It implements a display tree
     *  system that is very similar to that of conventional Flash, while leveraging modern GPUs
     *  to speed up rendering.</p>
     *  
     *  <p>The Starling class represents the link between the conventional Flash display tree and
     *  the Starling display tree. To create a Starling-powered application, you have to create
     *  an instance of the Starling class:</p>
     *  
     *  <pre>var starling:Starling = new Starling(Game, stage);</pre>
     *  
     */ 
    public class Starling extends EventDispatcher
    {
        /** The version of the Starling framework. */
        public static const VERSION:String = "1.2";