Я использую Aptana Studio 3 для написания JavaScript;он имеет отличную поддержку содержимого для встроенных типов, правильно выводит тип переменных из их источников и спасает жизнь при написании кода, который записывает код в строковый литерал, который записывает код в строковый литерал в HTML-документе.Тем не менее, поддержка контента и поддержка функций ScriptDoc были запутанными, медленными и приводящими в бешенство.Когда я пытаюсь написать класс / конструктор и документировать функцию как таковую, я могу поиграться с тегами ScriptDoc, чтобы получить помощь по содержимому:
-Не распознавать имя функции / класса как что-либо;
- Распознает конструктор как функцию, а класс - как тип, но не может распространить это распознавание на переменную.Это замечательно, если я хочу написать свой класс и никогда не использовать его;
-Познавать класс как тип, но не может понять конструктор как функцию.То есть он не будет подробно описывать параметры функции, описание или тип возвращаемого значения, но если я создам его экземпляр, он поможет мне с членами объекта.
Документация для функции ScriptDoc (из которойAptana извлекает пользовательскую информацию для справки по содержанию), которую можно найти по адресу http://wiki.appcelerator.org/display/tis/ScriptDoc+%28SDOC%29+2.0+Specification;, однако Aptana не распознает многие из перечисленных ключевых слов и распознает некоторые из них, которых там нет.Например, «@classDescription» указан в документации, но не распознается, тогда как «@class» распознается, но не указан в документации.Также обратите внимание, что выполнение действий в точности так, как они описывают, вообще не работает.
Может кто-нибудь помочь мне с примером «класса» JavaScript, задокументированным так, что помощник по кодам Aptana Studio 3 будет правильно описывать класс и конструкторПараметры, правильно определить тип назначенной переменной и правильно определить тип переменной, возвращаемой одним из ее методов, как это происходит с нативными типами?Используйте код ниже, добавляя блоки комментариев и теги по мере необходимости.Я удалил большую часть своей, так как постоянно с ними связывался, потому что они не работают.
/**
* 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)
Спасибо!
ОБНОВЛЕНИЕ: В отсутствие окончательного ответана Aptana's Jira, Tenderapp или StackOverflow я разработал ужасный хак, который никто никогда не должен использовать.Я включаю его в любом случае по двум причинам: это может быть полезно для разработчиков с точки зрения определения основной причины проблемы, и это может побудить их решить проблему, чтобы люди не могли использовать взлом.Это выглядит следующим образом:
// 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
Это работает, потому что код успешно вызывает вывод, и ScriptDoc успешно присоединяет документацию к коду, но ScriptDoc не может сам вызвать вывод (или делает это действительно сломанным способом, который никто не можеткажется, выяснить).Моя ставка по-прежнему заключается в том, что ScriptDoc работает над именами типов, как видно из представления индекса.В Aptana Studio 3.08 все мои типы были перечислены как имена «динамического типа» вместо имен, которые можно было бы разумно понять.В ночной сборке 02.02.2012 он перечисляет все мои конструкторы как Function<NameOfClass> и перечисляет NameOfClass.prototype отдельно (кажется, не помогает с ScriptDoc или выводом).
Я написалкод в блокноте, так что это не должно быть так сложно, как мне кажется, но я все равно был бы очень признателен за не взломанный ответ.Спасибо!
БОЛЬШЕ ОБНОВЛЕНИЙ:
Полное исследование исходного кода Aptana выявило множество различий между документацией и перечисленными функциями и фактической реализацией.Вы можете увидеть мои заметки об этом на https://jira.appcelerator.org/browse/APSTUD-4454.