ScriptDoc to document Prototype-based class definitions

[p1ometheas]

Hey gang,


I'm having troubles trying to get ScriptDoc to document my classes for auto-completion, etc. As mentioned in the thread subject, I'm using the Prototype class definition style. Is there some sort of trick I'm missing to get everything to come together properly?

I'd imagine there's gotta be some information specifically about this, somewhere out there -- I just can't seem to find it.

Anyhow, any help would be immensely appreciated!


update: and yes, I posted about this earlier... things aren't working like they seem to have been back in September... I was wondering if there had been any known regressions, or perhaps something's been changed on purpose, and documented somewhere...?

[mpetersen]

Hi prometheas,

This is the first that I've heard of this. Can you post a code excerpt where things aren't working the way that you expect them to? What Build of Aptana are you currently using?

Thanks,
Michelle

[ingo]

Hi Prometheas,

We also recently added this help topic: http://www.aptana.com/docs/index.php/Do ... _ScriptDoc

Which discusses prototype-based inheritance and gives an example of it inside Aptana.

We do have a number of tests to check against regression issues in Aptana, but please let us know if something appears not to be working as expected.

Best,
Ingo

[nonplus]

I think prometheus might be refering to the Prototype Linrary rather than the class.prototype = ...

I'm running into a similar issue using the MooTools JS framework. In MooTools, classes are declared as follows:

Code: Select all

var Base = new Class({
    method1: function(param1, param2) {
    },
    ...
});


and classes are derived from like this:

Code: Select all

var Derived = Base.extends({
    method2: function(p) {
    },
    ...
});


As far as ScriptDoc is concerned, these just declare two variables. I'd like to be able to indicate that Base and Derived are classes and that method1 and method2 are methods in the respective classes (I tried @memberOf without any luck).

[kobtron]

When you're extending a class you have to use the @alias tag this way:

Code: Select all

         var Namespace = function() {}
         
          Namespace.Class = function(arg1) {
          }
         
          Namespace.Class.prototype = {
             method: function(arg1) {
               
             }
          };

          /**
            @extends {Namespace.Class}
           * @param {Object} asdf
           */
          Namespace.Class2 = function(asdf) {
          }
         
          YAHOO.extend(Namespace.Class2, Namespace.Class, {
             /**
               @alias Namespace.Class2.prototype.method2
              * @param {Object} asdf
              */
             method2: function(asdf) {
               
             }
          });


[william583]

You either need to make a synchronous call to the server, explicitly make the call in the response handler, or use a closure callback - either manually or using a continuation transformer such as Narrative JavaScript or djax. Note that you can't just add a loop to keep checking for the new function, due to the single-threaded nature of JavaScript. A less obtrusive way to do the same thing involves DOM Manipulation. Simply insert a suitable script element into the DOM and the JavaScript will be loaded.220-602 It can be a child of either the head or body and its src property must be pointing to a JavaScript URL. There are several differences with XMLHttpRequest:
* The JavaScript will automatically be evaluated in much the same way as JavaScript linked in the static HTML is evaluated when the <script> tag is first encountered. You can declare a bare function or variable without adding it to the window.
* You can load JavaScript from external domains.
* The URL points to a specific Javascript resource. With XMLHttpRequest, there's more flexibility: you can, for example, send several JavaScript snippets inside different XML nodes.
* The DOM is affected in a different way. Even if the behaviour is transient, the script will be added to the DOM, whereas it would disappear after an XMLHttpRequest callback eval'd it.
(Watch for compatibility. See 640-553 * Inserting script element into the DOM means that if the file is cached in the browser then the cache is used. This is not possible with XMLHttpRequest. There's a variant of the pattern I'll call JavaScript Response in reference to the HTML Response pattern. The standard pattern refers to the situation where you're downloading a new set of functions, classes, and variables. In reality, 642-524 you're just adding new members to the DOM - some other code will then invoke it. In JavaScript Response, you grab a snippet of Javascript and eval it - the script is not wrapped inside a function (although it may define some functions that it calls). Under this variant, then, the browser is asking the server what to do next. Whereas in the standard pattern, the browser knows what to do, but not how to do it.