JSDoc

JSDoc je jezik za označavanje opisa sadržaja u datotekama sa JavaScript izvornim kodom. Koristeći komentare koji sadrže JSDoc, programeri mogu da dodaju opise programerskog interfejsa koda koji razvijaju. Ovo se zatim koristi za uređivanje, različitim alatima, tj. za dobijanje dokumentacije u popularnim formatima kao sto su HTML i RTF.

Istorijat

Prvi primer korišćenja sintakse slične Javadoc-u, za JavaScript je objavljen 1999. godine u Netscape/Mozilla projektu Rhino, u JavaScript izvršnom sistemu napisanom u Javi.

Sintaksa i semantika JSDoc-a su slične onima kod Javadoc sheme, koja se koristi za dokumentovanje koda pisanog u Javi. JSDoc je razlikuje od Javadoc-a, jer je specijalizovan za obradu dinamičkih svojstava JavaScripta.

JSDoc oznake

Neke od popularnijih oznaka koje se koriste u modernom JSDoc-u su:

Oznaka	Opis
@author	Ime programera
@constructor	Obeležava funkciju kao konstruktor
@deprecated	Obeležava metod kao prevaziđen
@exception	Sinonim za @throws
@exports	Prepoznaje izvezeni član iz modula
@param	Dokumentuje parametre metoda; indikator tipa podataka može biti dodat u vitičastim zagradama
@private	Označava da je član privatan
@return	Dokumentuje povratnu vrednost
@returns	Sinonim za @return
@see	Dokumentuje vezu sa drugim objektom
@this	Određuje tip objekta na koju ključna reč "this" ukazuje unutar funkcije
@throws	Dokumentuje izuzetak izdat od metode
@version	Daje broj verzije biblioteke

Primer

/**
* Креира инстанцу (појаву) Круга - (енгл. 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 + ".";
};

Upotreba JSDoc-a

• Google's Closure Linter i Closure Compiler. Ovaj drugi izvlači tip informacija neophodan za optimizaciju izlaznog JavaScript-a.
• Popularni editor Sublime Text podržava JSDoc korišćenjem dodatka DocBlockr.
• Sintaksa JSDoc-a je detaljno opisana u knjizi Foundations of Ajax. ISBN 978-1-59059-582-4. ].
• IntelliJ IDEA, NetBeans i RubyMine prihvataju sintaksu JSDoc-a.
• Eclipse IDE ima proširenja koja prihvataju JSDoc sintaksu. Aptana Studio zasnovan na Eclipse-i podržava ScriptDoc, i uključene JavaScript datoteke su komentarisane u ScriptDoc-u.
• Mozile Arhivirano na sajtu Wayback Machine (6. oktobar 2018), Mozilla Inline Editor, koristi JSDoc.
• Helma razvojno okruženje koristi JSDoc.
• SproutCore dokumentacija je generisana korišćenjem JSDoc-a.
• Visual Studio, WebStorm i mnoga druga integrisana razvojna okruzenja ili tekst editori omogućuju kompletiranje koda i ostale pomoći zasnovane na JSDoc komentarima.

Spoljašnje veze

• Zvanični veb-sajt
• Zvanični JSDoc Github, za ažurirani kod.
• "Annotating JavaScript for the Closure Compiler", alat za finalnu obradu dokumenata, Google Developer veb sajt.