Kodunuzu Daha Anlaşılır ve Otomatik Dokümanlı Yazmanın Kolay Yolu: JSDoc
Kodunuzu Daha Anlaşılır ve Otomatik Dokümanlı Yazmanın Kolay Yolu: JSDoc
Kodumuzun düzgün bir biçimde çalışıp çalışmaması kadar da geliştirilebilir ve anlaşılır olup olmadığı da onun ne kadar kaliteli bir kod olduğunu belirliyor.
Kodumuzu daha anlaşılabilir en etkili yollarından birisi de onu nitelikli bir şekilde açıklamaktan geçtiğini unutmayalım. Peki gerçekten kaç kişi hem koduna yorum düşüp hem de ayrıca nasıl çalıştığı hakında bir doküman yazıyor? Bir elin parmakları kadar mı? Gelin bu iki işi aynı anda yapmanın kolay yolu olan otomatik doküman oluşturuculara JavaScript dili için bir göz atalım.
Otomatik Doküman Oluşturucu Nedir?
Otomatik doküman oluşturucu aslında ayrı bir program olup tek yaptığı iş kodunuzu okuyup yorumlamaktır. Bu program kodunuzu string olarak okur, dil yapısına göre parçalar ve eklediğiniz yorumları da kullanarak bir HTML olarak ya da eklentilerle MarkDown gibi formatlarda doküman oluşturabilir, küçük eklemeler yaparak bunları doğrudan websitesi olarak kullanabilirsin.
Java için Javadoc, PHP için phpDocumantor, JavaScript için ise JSDoc programlarını örnek gösterebiliriz.
Avantajları Nelerdir?
- Kaynak koduna yorum düştüğünüz için kod yabancı kişilerce daha kolay anlaşılır.
- Kodun kullanımı ve püf noktaları hakkında ayrıca doküman yazmanıza gerek kalmaz. Sadece kaynak kodunuza yorum düşmeniz bunu yapmak için yeterlidir.
- Popüler olarak kullanılan çoğu IDE ve bazı text editörler bu yorumları algılar ve kodunuzu kullanırken bu bilgileri görselleştirerek hızlı geliştirme yapmanıza olanak tanır.
- JavaScript gibi tip güvensiz diller için sanki derleme yapılıyormuş gibi tip kontrolü yapılmasına olanak sağlar
Nasıl kullanılır?
JSDoc kendi yorumlarının /** ile başlamasını zorunlu tutar. // , /* gibi normal yorum bloğu başlangıçlarını veya ikiden fazla yıldız olanları görmezden gelir.
/** JSDoc için uygun yorum yazımı *//**
* Bu şekilde de kullanabilirsiniz
*/
function foo() {
}JSDoc’un parser’ının yorumlayacağı her özel kelimeye tag yani etiket denir.Etiketler @ karakteri ile başlar.
Bilgisayarınıza npm’i kurduktan sonra npm install -g jsdoc ile global olarak bilgisayarınıza veya npm install jsdoc komutu ile lokal olarak sadece şu an üzerinde bulunduğunuz projeye yükleyebilirsiniz.
Programı çok temel olarak jsdoc <dosya-ismi> şeklinde kullanıabilirsiniz. Bu size out adında bir klasör açacak ve çıktıları içine yükleyecektir. Kendi konfigrasyonunuzu json tipinde bir dosyaya yazarak bunu -c <json-dosyasının-yolu>ekleyeyerek kullanabilirsiniz.
Detaylar için bkz.:
To customize JSDoc's behavior, you can provide a configuration file to JSDoc in one of the following formats: A JSON…jsdoc.app
Hangi Etiketler Var?
Aynı HTML’de olduğu gibi burada da block ve inline olmak üzere iki farklı etiket türü bulunuyor. Block etiketler tüm satırı kaplarken, inline etiketler ise satırın içindeki bir veya daha fazla kelimeyi kaplar. Inline etiketler normal yazıdan ayrılabilmek içi { } arasına yazılır.
Sıklıkla kullanılan bazı etiketler şöyledir:
Inline etiketler:
link: Dokümandaki bir yere yahut harici bir bağlantıyı linkler.
Block etiketler:
construct: Sınıfa ait kurucu fonksiyonları tanımlarken kullanılır.class: Sınıf tanımlarken kullanılır.default: Varsayılan değeri belirtir.description: Açıklama eklemenizi sağlar.summary:description‘a benzer olsa da daha detaylı olarak anlatım yapılır.example: Örnek kullanım gösterirken kullanılır.function: Fonksiyon veya methodları tanımlamak için kullanılır.param: Fonksiyonun parametrelerini tanımlar.argveyaargumentolarak da kullanılır.readonly: O alanda sadece okuma işlemi yapılabileceğini anlatır.return: Fonksiyonların dönüş değerini belirtir.returnsolarak da kullanılır.property: Bir nesnenin property’sini tanımlar.propolarak da kullanılır.see: Buna da bakılsa iyi olur dediğiniz linkleri gösterir.author: O elemanı yazan kişiyi belirtir.type: Tip kontrolü için kullanılır.name: Bir nesneye isim vermemizi sağlar.callback: Callback fonksiyonlarını tanımlarken kullanılır.copyright: Telif hakkı belirtir.ignore: Yazıldığı kısmın görmezden JSDoc tarafında görmezden gelinmesini sağlar.module: JavaScript modul’ü oluştururken kullanılır.namespace: Bir namespace’i tanımlar.override: Bir kalıtım alınan ebeveyn özelliğini ezdiğimizi vurgular.since: Bu özelliğin eklendiği tarihi gösterir.this:thisanahtar kelimesinin neyi işaret ettiğinni belirtir.throw: Fırlatılacak hatayı gösterir.version: Ekleme yapıldığı versiyonu belirtir
Kullanabileceğiniz tüm etiketlere buradan ulaşabilirsiniz: https://jsdoc.app/index.html
Örnek Kullanımı
Sunucu adındaki modül içindeki portDinle adında, url ve port olarak iki parametre alan, bu bilgileri kullanarak gelen istekleri dinleyen fonksiyonumuz için örnek kullanım şöyle olabilir:
VSCode kullanırken fonksiyonun üstüne geldiğimizde çıkan bilgi kutusu:
Oluşan doküman:
