Minjole

JSDoc

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

Историјат

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

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

JSDoc ознаке

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

Ознака	Опис
@author	Име програмера
@constructor	Обележава функцију као конструктор
@deprecated	Обележава метод као превазиђен
@exception	Синоним за @throws
@exports	Препознаје извезени члан из модула
@param	Документује параметре метода; индикатор типа података може бити додат у витичастим заградама
@private	Означава да је члан приватан
@return	Документује повратну вредност
@returns	Синоним за @return
@see	Документује везу са другим објектом
@this	Одређује тип објекта на коју кључна реч "this" указује унутар функције
@throws	Документује изузетак издат од методе
@version	Даје број верзије библиотеке

Пример

/**
 * Креира инстанцу (појаву) Круга - (енгл. 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 1-59059-582-3.
• IntelliJ IDEA, NetBeans и RubyMine прихватају синтаксу JSDoc-а.
• Eclipse IDE има проширења која прихватају JSDoc синтаксу. Aptana Studio заснован на Eclipse-и подржава ScriptDoc, и укључене JavaScript датотеке су коментарисане у ScriptDoc-у.
• Mozile, Mozilla Inline Editor, користи JSDoc.
• Helma развојно окружење користи JSDoc.
• SproutCore документација је генерисана коришћењем JSDoc-а.
• Visual Studio, WebStorm и многа друга интегрисана развојна окрузења или текст едитори омогућују комплетирање кода и остале помоћи засноване на JSDoc коментарима.

Видети такође

• Поређења генератора документација.

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

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

Споменице и захвалнице

100 измена

25%