JSDoc JavaScript kaynak dosyalarına ek açıklama için kullanılan metin işaretleme dilidir. JSDoc yorumları kullanarak programcılar uygulamanın ne yaptığını yazabilir ve bunu dokümante edebilir. Bundan sonra yazılanlar farklı araçlar vasıtası ile HTML veya Zengin Metin Biçimi haline getirilir.
En erken Javadoc stili yazım 1999'da Netscape/Mozilla projesi olarak yayınlandı. Rhino Java ile yazılmış bir JavaScript motorudur.
JSDoc sözdizimi ve semantiği Javadoc düzenine benzer. Javadoc Java için dokümantasyan şemasıdır. JSDoc Javadoc'tan JavaScript'in dinamik davranışından dolayı farklılıklar gösterir.
Modern JSDoc'ta kullanılan popüler açıklama etiketlerinden bazıları şunlardır:
| Etiket | Açıklama |
|---|---|
| @author | Geliştirici Adı |
| @constructor | Fonksiyonu kurucu olarak işaretler |
| @deprecated | Metodu kullanımdan kaldırıldı olarak işaretler |
| @exception | @throws eş anlamlısı |
| @exports | Modülü tarafından dışarıya gösterilen üyeyü tanımlar |
| @param | Metodun parametresini dokümante eder, datatipi tanımlayıcı süslü parantez içinde yazılarak tanımlanır. |
| @private | Üyenin özel olduğunu bildirir. Başka bir class'tan erişilemez. |
| @return | Dönüş değerini belirtir |
| @returns | @return eş anlamlısı |
| @see | Başka bir objeye referans verir |
| @this |
fonksiyon içerisinde @this'in ne anlama geldiğini belirtir. |
| @throws | Metod tarafından atılan hatayı dokümante eder. |
| @version | Kütüphanenin sürümünü belirtir. |
/**
* Creates an instance of Circle.
*
* @constructor
* @author: moi
* @this {Circle}
* @param {number} r The desired radius of the circle.
*/
function Circle(r) {
/** @private */ this.radius = r;
/** @private */ this.circumference = 2 * Math.PI * r;
}
/**
* Creates a new Circle from a diameter.
*
* @param {number} d The desired diameter of the circle.
* @return {Circle} The new Circle object.
*/
Circle.fromDiameter = function (d) {
return new Circle(d / 2);
};
/**
* Calculates the circumference of the Circle.
*
* @deprecated
* @this {Circle}
* @return {number} The circumference of the circle.
*/
Circle.prototype.calculateCircumference = function () {
return 2 * Math.PI * this.radius;
};
/**
* Returns the pre-computed circumference of the Circle.
*
* @this {Circle}
* @return {number} The circumference of the circle.
*/
Circle.prototype.getCircumference = function () {
return this.circumference;
};
/**
* Find a String representation of the Circle.
*
* @override
* @this {Circle}
* @return {string} Human-readable representation of this Circle.
*/
Circle.prototype.toString = function () {
return "A Circle object with radius of " + this.radius + ".";
};