Hacking Code Assist in Aptana 3 (JavaScript)

 May, 11 - 2012   2 comments   How ToThings that are broken

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!


Related articles

 Comments 2 comments

  • mizar001 says:

    Aptana studio 3 code completion related to javascript is one of the worst I’ve ever seen.

    Using the code assist is not only a loss of time for 2 out of 5 times i use it , but it’s also a loss of code, because in some cases it replaces my trailing code and subsequent lines with a useless snippet. So i’m forced to ctrl+z most of times and find the function/variable browsing the right files.

    Also commenting blocks or single lines with the shortcut key is adding an extra blank line at the end of block, wich i have to remove manually.

    And the completion is so random and bizarre that i cannot understand how as3 is so popular.

    After all of your set-up are you using as3 succesfully on javascript right now ?

    Actually as3 failed me, so i get stick with komodo (less buggy at least)

     

    ReplyReply

  • Leave a Reply

    Your email address will not be published. Fields with * are mandatory.

    You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>