Aptana Studio 3 JavaScript Content Assist woes

Question

I'm using Aptana Studio 3 to write JavaScript; it has excellent content assistance for the built in types, it infers the type of variables from their sources correctly, and it is a life saver when writing code that writes code in a string literal that writes code in a string literal in an HTML document. That said, the content assist and supporting ScriptDoc functionality has been confusing, slow, and infuriating. When I attempt to write a class/constructor and document the function as such, I can get fiddle with ScriptDoc tags to get content assist to:

-Not recognize the name of the function/class as anything;

-Recognize the constructor as a function, and the class as the type, but fail to propagate that recognition to a variable. This is great as long as I want to write my class and never use it;

-Recognize the class as a type, but fail to understand the constructor as a function. That is, it won't elaborate on the function's parameters, description, or return type, but if I instantiate it, it will help me out with the object's members.

The documentation for the ScriptDoc feature (from which Aptana derives user-defined content assist information) can be found at http://wiki.appcelerator.org/display/tis/ScriptDoc+%28SDOC%29+2.0+Specification; however, Aptana doesn't recognize many of the keywords listed, and recognizes some that are not there. For instance, "@classDescription" is listed in the documentation but is not recognized, whereas "@class" is recognized but not listed in the documentation. Also note that doing things exactly as they describe there does not work at all.

Can anyone help me with an example of a JavaScript "class" documented such that Aptana Studio 3 code assist will properly describe the class and constructor's parameters, correctly deduce the type of the assigned variable, and correctly deduce the type of a variable returned by one of its methods, as it does with native types? Use the code below, adding comment blocks and tags as necessary. I've removed most of mine, as I've been messing with them continuously, because they don't work.

/**
 * Constructor for Vector class
 */
function Vector(nX, nY) {
    this.x = nX || 0;
    this.y = nY || 0;
}
Vector.prototype = {
    x: 0,
    y: 0,
    /**
     * make a new Vector out of me
     */
    copy: function () {
        return new Vector(this.x, this.y);
    },
    /**
     * compare to some other vector.  Are they equal?
     * @param {Vector} vOther   some other Vector
     */
    equals: function (vOther) {
        //vOther should have content assistance, too.
        return (vOther.x === this.x) && (vOther.y === this.y);
    }
};
var v = new Vector(1,2);  //Should describe Vector class/constructor, types & purposes of nX & nY (Numbers)
var c = v.copy();         //Should recognize v as a Vector and describe v.copy()
c.copy();                 //If c.copy() is described properly, return type is correctly deduced & you win!
//bonus points if you can get it to inherit from something and describe c.inheritedMethod(someParameter)

Thanks!

UPDATE: In absence of a conclusive response on Aptana's Jira, Tenderapp, or StackOverflow, I have developed a terrible hack that no one should ever use. I include it here anyway for two reasons: it may be informative to the developers in terms of determining the root cause of the issue, and it may motivate them to fix the issue to prevent people from using the hack. It goes like this:

// Only recognizes global names
/**
 * This constructor will still be listed as returning 'none', but successfully infers
 * the type of a 'new' expression.  Adding a return tag will break this effect.
 * @constructor (can't tell if this tag does anything)
 */
MyClass = function () {
    // properties added here still won't work
}

/**
 * Describes an obvious property.
 * @type {String}
 */
MyClass.prototype.obviousProperty = "obvious";
// only works for properties declared like that

/**
 * Logs a comment on the parameter's property and returns this object (for chaining)
 * @param {MyClass} oProperty This is what you see for help on calling this method,
 *                            but it doesn't affect CA inside the method
 * @return {MyClass}          This makes the CA for calling the method correctly list
 *                            the return type, but doesn't cause inference of the
 *                            returned value's type.
 */
MyClass.prototype.commentOn = function (oProperty) {
    // hack below makes CA work when you type oProperty.
    log("obvious property is " + oProperty.obviousProperty);

    // the type of 'this' is not understood; I don't even know if the ScriptDoc
    // standard has a mechanism for it
    return this;

    // BEGIN HACK (note that this code is unreachable)

    // force working inference from assignment directly to symbol
    oProperty = new MyClass;

    // force working inference of return type
    return new MyClass;

    // END HACK
}

var foo = new MyClass; // see class description from above
var bar = new MyClass; // see it again, so it's not a crazy fluke
var baz = foo.commentOn(bar); // CA suggests & documents commentOn
baz. // CA suggests & documents obviousProperty & commentOn

It works because code successfully causes inference and ScriptDoc successfully attaches documentation to code, but ScriptDoc fails to cause inference by itself (or does it in a really broken way that no one can seem to figure out). My bet is still on ScriptDoc chomping on type names, as is evident in the index view. On Aptana Studio 3.08, it listed all of my types as 'dynamic-type' names instead of the names one would reasonably understand them to have. On the 2/2/2012 nightly build, it now lists all of my constructors as Function<NameOfClass> and lists NameOfClass.prototype separately (doesn't seem to help with ScriptDoc or inference).

I've written code in Notepad, so this shouldn't be as big a deal as I feel like it is, but I still would really appreciate a non-hack answer. Thanks!

MORE UPDATE:

An exhaustive investigation of the Aptana source code revealed a lot of differences between the documentation and listed features and the actual implementation. You can see my notes about this at https://jira.appcelerator.org/browse/APSTUD-4454.

Answer 1

It's really busted, but here's what I came up with: http://karoshiethos.com/2012/05/11/hacking-code-assist-in-aptana-3-javascript/