JSDoc

JSDoc је језик за означавање описа садржаја у датотекама са JavaScript изворним кодом. Користећи коментаре који садрже JSDoc, програмери могу да додају описе програмерског интерфејса кода који развијају. Ово се затим користи за уређивање, различитим алатима, тј. за добијање документације у популарним форматима као сто су HTML и RTF.

Историјат

Први пример коришћења синтаксе сличне Javadoc-у, за JavaScript је објављен 1999. године у Netscape/Mozilla пројекту Rhino, у JavaScript извршном систему написаном у Javi.^[1]

Синтакса и семантика JSDoc-а су сличне онима код Javadoc схеме, која се користи за документовање кода писаног у Javi. JSDoc је разликује од Javadoc-а, јер је специјализован за обраду динамичких својстава JavaScripta.

JSDoc ознаке

Неке од популарнијих ознака које се користе у модерном JSDoc-у су:

Пример

/**
* Креира инстанцу (појаву) Круга - (енгл. Circle).
* 
* @constructor
* @this {Circle}
* @param {number} r Очекивани полупречник круга.
* /
function Circle(r) {
   /** @private */ this.radius = r;
   /** @private */ this.circumference = 2 * Math.PI * r;
}

/**
* Креира нови Круг датог полупречника.
* 
* @param {number} d Жељени пречник круга.
* @return {Circle} Нови објекат типа Круг.
* /
Circle.fromDiameter = function (d) {
   return new Circle(d / 2);
};

/**
* Израчунава обим Круга.
* 
* @deprecated
* @this {Circle}
* @return {number} Обим круга.
* /
Circle.prototype.calculateCircumference = function () {
   return 2 * Math.PI * this.radius;
};

/**
* Враћа израчунати обим Круга.
* 
* @this {Circle}
* @return {number} Обим круга.
* /
Circle.prototype.getCircumference = function () {
   return this.circumference;
};

/**
* Налази стринг репрезентацију Круга.
* 
* @override
* @this {Circle}
* @return {string} Репрезентација овог Круга као стринг.
* /
Circle.prototype.toString = function () {
   return " Објекат Круг полупречника " + this.radius + ".";
};

Употреба JSDoc-а

• Google's Closure Linter и Closure Compiler. Овај други извлачи тип информација неопходан за оптимизацију излазног JavaScript-а.
• Популарни едитор Sublime Text подржава JSDoc коришћењем додатка DocBlockr.
• Синтакса JSDoc-а је детаљно описана у књизи Foundations of Ajax. ISBN 978-1-59059-582-4. ].
• IntelliJ IDEA, NetBeans и RubyMine прихватају синтаксу JSDoc-а.
• Eclipse IDE има проширења која прихватају JSDoc синтаксу. Aptana Studio заснован на Eclipse-и подржава ScriptDoc, и укључене JavaScript датотеке су коментарисане у ScriptDoc-у.
• Mozile Архивирано на сајту Wayback Machine (6. октобар 2018), Mozilla Inline Editor, користи JSDoc.
• Helma развојно окружење користи JSDoc.
• SproutCore документација је генерисана коришћењем JSDoc-а.
• Visual Studio, WebStorm и многа друга интегрисана развојна окрузења или текст едитори омогућују комплетирање кода и остале помоћи засноване на JSDoc коментарима.

Референце

Спољашње везе

• Званични веб-сајт
• Званични JSDoc Github, за ажурирани код.
• "Annotating JavaScript for the Closure Compiler", алат за финалну обраду докумената, Google Developer веб сајт.