Belgelerinize meta veri ekleme
İyi belgeler sağlamak, her geliştirici için önemli bir görevdir. Meslektaşlarınızın akıl yürütmenizi ve belki de düşünce sürecinizi hızlı bir şekilde anlamalarına yardımcı olmakla kalmaz, aynı zamanda birkaç ay sonra koda geri dönmeniz durumunda koda daha hızlı girmenize de yardımcı olur.
Bu nedenle, JSDoc yorumlarıyla kullanmak için (tamamlanmamış) bir özel etiket listesi oluşturmayı düşündüm. Bunlar benim kişisel olarak en sık kullandığım ve gerçek bir fayda sağladığı kanıtlanmış olanlardır.
Temel bir başlangıç
Aşağıdaki kod örneği, her belge için kullanılması gereken basit, temel bir örneği gösterir. Amacı, parametreleri ve dönüş türünü açıklar.
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Belgelerdeki örnek kod
Belirli kullanım durumlarını daha net hale getirmek için “@example” etiketiyle gerçek bir satır içi kod örneği sağlayabilirsiniz. Bu etiket, gerçek dünya senaryosunda olası uç durumları hızlı bir şekilde göstermek için de kullanılabilir.
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Hangi modülün üyesi
Belgelenen kodu hangi modülün veya üst değişkenin barındırdığını tanımlamak için “@memberOf” etiketini kullanın.
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Bağlantı açıklaması
Bazı URL'leri ana dokümantasyonun içine yapıştırmak yerine, doğru biçimlendirilmiş bir URL dokümantasyonu sağlamak için “@see” etiketini “@link” etiketi ile birlikte kullanabilirsiniz.
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Genel tür belgeleri
Kodunuz genel türler kullanıyorsa, genel tür adını tanımlamak için “@şablon” etiketini kullanabilirsiniz. Bu ad daha sonra tür referansı olarak ortak “@param” etiketlerinde kullanılır.
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Bir kod parçasının yazarını tanımlama
Bazı durumlarda, yazara da açıklama eklemek önemlidir. Bu, “@author” etiketi ile kolayca gerçekleştirilebilir. Sadece adınızı değil, aynı zamanda iletişim referansı olarak bir e-posta da sağlayabilirsiniz.
/**
* @author Tom Schönmann <tom@flaming.codes>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Kullanımdan kaldırılmış kod
Tam olarak beklediğiniz şeyi yaptığı için "@deprecated" etiketi hakkında söylenecek fazla bir şey yok. Bu etiket, API'lerde yaygın olarak kullanılır ve yeni koda da başvurabilir.
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
sürüm
Verilen kod için bir sürümü belgelemek için “@version” etiketini kullanın. Bu etiketin uygulama sürümüne atıfta bulunmadığını, ancak gerçekten kendi sürümüne atıfta bulunduğunu unutmayın. Bu sürümün artması, bu özel kodun değiştiği anlamına gelir.
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
Kodun kullanıma hazır olduğu zamandan beri
Aşağıdaki kodun genel API'ye hangi sürüm numarasından eklendiğini belgelemek için “@since” etiketini kullanabilirsiniz. Burada dikkat edilmesi gereken önemli nokta, sürümün artık uygulama kapsamına atıfta bulunmasıdır. Bu, daha önce belgelediği belirli kod bloğunun kapsamına giren “@versiyon” etiketiyle çelişir.
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
