I’ve spent this morning trying to get ASDoc to generate code documentation for the JASPA APIs, with mixed results.

I encountered problems straight away with the extended globals that JASPA uses. For example The DOM API defines a native Window class which extends the ECMAScript global. Of course in AS3 you cannot extend the global.

Eventually I managed to trick ASDoc into completing, but it has opened up further cans of worms. There are a whole bunch of practices in the JASPA code base that the AS3 compiler really doesn’t like. I’ve tried to be strict, but apparently not strict enough. In some cases I feel that AS3 is just being unreasonable, for example, you cannot have private constructors in AS3. A common practice for singleton classes is many OOP languages.

Here’s another example, where an extended event class provides access to an extended target –

public class EventTarget {
}

public class Event {
    public function get target():EventTarget;
}

public class SpecialEventTarget extends EventTarget {
}

public class SpecialEvent extends Event { 
    override public function get target():SpecialEventTarget;
}

The overridden getter that returns a sub-type of the target is considered invalid. I don’t see how this is bad practice. Surely a more specific type of event should be allowed to return a more specific type of target, especially as the extended target still has all the traits of the original target.

Of course you can always cast with the as operator:

mySpecialEvent.target as SpecialEventTarget;

The question is, do I really want JASPA to be tied so closely to AS3? At the end of the day it is a separate language, and is designed for compiling into JavaScript not for emulating ActionScript.

I am not caught between two options.
1. Alter the JASPA codebase to be even more like AS3
2. Write a JAS documentor, jasdoc

What do you think?