Project: aptanastudio
Issue APSTUD-4445: Content assist, inference, and documentation languages lack expressions to explicitly relate types to identifiers
The languages defined for adding documentation that affects content assist (ScriptDoc, SDocML, JSCA JSON) have type expressions whose grammer is inadequate in cases where the type is not specifically known beforehand, but can reliably be deduced from parameters. Consider the ES5 Object.create, which creates a new object with a prototype specified by its parameter: {code:JavaScript} foo = new KnowTypeWithDocumentedProperties; bar = Object.create(foo); {code} In that case, bar will have the same properties as foo. However, it is not possible to infer them from the (hypothetical future) documentation for the Object.create method because the documentation languages lack a way to express that the return type will be the same as one of the parameters. Perhaps more common: {code:JavaScript} BaseClass.prototype.chainableMethod = function () { /* do something... */ return this; } DerivedClass.prototype = new BaseClass; exampleInstance = new DerivedClass; exampleReturn = exampleInstance.chainableMethod(); {code} It is currently impossible to express that chainableMethod returns the same type as the object that owns it. At best, inference will be able to guess that exampleReturn is an instance of BaseClass. If many types derive from BaseClass, this is a problem, since content assist will be unable to infer any of the subclass properties after the call to chainableMethod, and a chainable method's purpose is to conveniently call additional methods on the return value. The following would be really maddening to document: {code:JavaScript} dojo.declare("my.ClassName", Superclass, { constructor: function () { /* ... */ }, someProperty: /* ... */ }); instance = new my.ClassName; {code} All of the properties that should be inferred for instance are in the parameters to dojo.declare; some day, when the ScriptDoc tags for assigning class membership work for inference, it will be possible for dojo users to document the class, but it will still be difficult/impossible for the authors of dojo.declare to provide type information. Rather than add special cases in the Aptana source to deal with each of these specifically (and add more as they appear), it is preferable to extend the documentation languages' type expressions to include operators or new tags capable of explicitly stating a type's relationship to an identifier. Because inference from simple assignments is now working quite well, the simplest solution might be a 'typeof' operator in ScriptDoc/SDocML/JSCA type expressions whose operand is a JavaScript expression. The same inference code that is now working would evaluate the provided expression in the context of the invocation where it's found to determine the return type.
Story points: 13