JSDoc

Из Википедије, слободне енциклопедије
Иди на навигацију Иди на претрагу

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

Историјат[уреди]

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

Синтакса и семантика 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 978-1-59059-582-4.].
  • 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 коментарима.

Референце[уреди]

  1. ^ http://lxr.mozilla.org/mozilla/source/js/rhino/examples/jsdoc.js Archived 2013-04-15 at Archive.today. Мозилин пројекат, 6. мај 1999.

Спољашње везе[уреди]