Hacking Code Assist in Aptana 3 (JavaScript)

I wanted to share some quick notes on how to get JavaScript code assist “working” under the latest version of Aptana Studio.

Note: As far as I can tell, this feature is very buggy, and as such, YMMV.

There are three features that I find particularly desirable:

• Jump-to-definition: A Command-Click opens the file to the location where the highlighted function (etc) is defined. Probably the most important / useful.
• Code-completion: a drop-down of possible entries appears as you type / upon pressing Control-Space.
• Code-hints: Class constructor and method signatures appear as you type / upon mouse hover, displaying helpful information about method signatures & parameters.

Sounds pretty awesome, huh? Too bad it doesn’t work as advertised. Let’s talk about what’s busted.

• The SDocGen tool only seems to catch classes that are defined globally, so if you’re organizing your functions (as you should) into requirejs define calls (for instance), your comments won’t get picked up.
• Using a @return tag inside a constructor function will seem to work ok, but it tramples the class’s method definitions, so I avoid it in that context. The same @return tag inside method functions doesn’t seem to have this issue.
• The opening documentation tag is “/**” (Note: that’s 2 asterisks). The closing documentation tag is “*/”. Nothing else seems to work.
• I’ve seen code hints (eg for google maps) that seemed to work using the object-literal syntax. I never got this to work. Lucky for me, I don’t define my classes that way.

That first bullet is nearly impossible to work around, and I eventually quit trying. Instead, I hacked around it by appending the following structure to the bottom of my file:

if (false)
{
  MyClass = function (xyz)
  {
    /**
      Documentation here
      @param {String} xyz This text appears as a hint while you enter the xyz parameter
    */
  }
  
  MyClass.prototype.method = function ()
  {
    /**
      Method documentation here
      @return {Number}
    */
  }
}

Unfortunately, that means repeating yourself a bit, but everything seems to work. The “if (false)” pattern keeps this code from executing at runtime, but SDocGen will pick up your comments for documentation. When you Command-click (I’m on OS X) a class or method name in your code, it will jump to the first occurrence in the definition file, ie the correct one. Provided you’re defining one class per file, you shouldn’t have any collisions.

I discovered that a limited set of HTML tags are supported. I’ve had success with UL/LI, STRONG, EMPHASIS, BR, TABLE/TR/TD. I was even able to get a simple style-sheet to work, but that was nearly useless. The only thing that worked reliably was colors, and it was necessary to omit the ‘#’ from my hexadecimal colors. HTML did not work for method-parameter pop-up help. I’ll probably avoid this feature for now.

SDocGen is available on github; maybe someone can fix it?

Good luck!