Ekip içerisinde ve ekipler arasında bilgi alışverişini ve iletişimi güçlendirmemizi sağlayan en etkili yöntemlerden biridir dokümantasyon oluşturmak. Yazılım geliştirirken en son yöneldiğimiz ve elemesi gereken bir şey olduğunda ilk elediğimiz şey muhtemelen dokümantasyonlardır. Eğer bir iletişim söz konusuysa gün sonunda dokümantasyonu çıkaranın daha fazla zaman kazancı olduğunu düşünmekteyim. Bize zor gelecek olan durumlar aslında işlerimizi kolaylaştırıyor. Hazırladığımız servislerin dokümantasyonu için Swagger gibi araçlar kullanmaktayız. Fakat projemde her bir fonksiyon ve sınıf için dokümantasyon çıkarabilmek için arayışa başladım. Amacım basit bir şekilde kurulumunu yapıp ve dokümanını statik olarak alabileceğim dokümantasyon aracıydı, oluşturduğum serverless fonksiyonlarının her biri için tanımlama yapabildiğim JSDoc ile karşılaştım.
JSDoc Nedir?
JavaScript dili için kullanılan bir doküman oluşturucudur. Bulunduğu klasördeki tüm kodu ve ya ayarlarda belirtilmiş yoldaki klasörlerin içindeki JavaScript uzantılı dosyaları analiz etmektedir. Dosyalarda belirtilen doküman tanımlamalarına göre statik HTML sayfası oluşturur. Bu HTML sayfası JavaScript dosyaları içerisindeki bütün tanımlamaları içerir.
JSDoc Kurulumu
JSDoc kurulabilmesi için Node ve Npm yüklü olması gerekmektedir. İlk olarak bilgisayarımıza global bir şekilde kurulumunu yapıyoruz.
npm install -g jsdocVe uygulamanızın bulunduğu package.json dosyamıza eklemek için aşağıdaki komutu uygulayalım
npm install jsdoc --save-devJSDoc dokümantasyonu kaynak koddaki yorum satırlarındaki tanımlara göre oluşturmaktadır. Oluşturduğumuz fonksiyon, sınıf ve değişkenlerin üstüne yazdığımızda dokümantasyonunu oluşturmaya başlayabiliriz. Yorum satırı aşağıdaki örnek gibi olmalıdır
/** @function kullaniciOlustur* @param {string} isim - Kullanıcı ismi* @param {string} soyisim - Kullanıcı soyismi* @param {number} yas - Kullanıcı yaşı*/
Yukarıda görüldüğü gibi yorum satırında /** ile başlatıyoruz ve bitirirken */ ile bitiririz. Arada olan her bir satır başlangıcına * eklememiz gerekir. JSDoc içerisinde bir çok etiket mevcuttur. Bu etiketleri kullanarak tanımlamalarımızı gerçekleştirebilmekteyiz. Daha fazla etiket detayını JSDoc sayfasında bulabilirsiniz.
Örnek göstermeden önce konfigürasyonları tanımlamak istiyorum. Bu konfigürasyon sayesinde çıktının nerede olacağı, hangi klasörde bu tanım araması gerçekleşeceğini, hangi tema kullanacağı gibi ayarları yapabileceğiz.
Kullandığım basit ayar dosyasını yukarıda görmektesiniz. Source objesi içersinde “include” alanı hangi klasör dahil olduğunu, “includePattern” hangi örüntüde bir dosya içereceğini ve “excludePattern” hangilerinin dahil olmayacağını göstermektedir.
Bunaltmadan opts objesine gelmek istiyorum. Burada “recurse” alanı true yaptığımızda klasör ve içerisindeki klasör ve dosyaları tek tek kontrol edip dokümanını oluşturmaktadır. “destination” Alanı statik dosyalarımızın çıkacağını alanı belirlemektedir. “readme” alanıysa doküman karşılama sayfasında gösterilmesini sağlayacağımız “readme.md” dosyasının alanı yazılmalıdır.
Ve ayarları yaptıktan sonra tek bir işlemimiz kaldı. package.json dosyasına script olarak komutumuzu tanımlayacağız. Script objesi içersinde aşağıdaki şekilde tanımlayabilirsiniz. “doc” yapmak zorunda değilsiniz istediğiniz komutu yazabilirsiniz.
"doc": "jsdoc -c jsdoc.config.json"Ayarlarımızı tamamladık ve artık işe koyulabiliriz.
Yukarıdaki gibi basit bir şekilde fonksiyon oluşturduk. Bu fonksiyon tanımı için yorum satırlarında parametreleri belirttik. Bir fonksiyonumuzun olduğunu bu fonksiyonun 3 parametre aldığını ve bu parametrelerin tiplerini belirttik. Return parametresinde fonksiyonumuzun çıktısı nasıl olacağını, see parametresinde ise daha detaylı bilgi için link bıraktık. Terminalden aşağıdaki komutu çalıştırdığımızda aldığımız çıktıya birlikte bakalım
npm run doc
Ayar dosyamızda çıktı oluşacağı belirtiğimiz yolda docs klasörümüz oluştu. Bu klasör içersinde fonts,scripts ve styles klasörleri bizim dokümantasyonumuzun gereçlerini göstermektedir.
Ayar dosyasında belirttiğimiz readme.md içerisindeki “Hello Everyone!” yazısı aktarıldığını gözlemlemekteyiz. Sağ tarafta ise bizim fonksiyonlarımızın listelendiği yerdir belli bir namespace ve module eklemediğimizden dolayı Global altında listelenmektedir.
Global sayfasına gittiğimizde tanımlamalarını yaptığımız fonksiyonu görmekteyiz ve fark ettiyseniz yukarıda yaptığımız tanımlamalar dokümantasyon haline geldi. Bu şekilde oluşturduğumuz fonksiyonların dokümanını çıkarabiliriz.
Tanımlamalar hakkında şimdilik daha fazla örnek vermeden “Template” eklemeye değinmek istiyorum. JSDoc Github sayfasında templates kısmı görülmektedir. Bu temalar topluluk tarafından geliştirilmektedir ve en popüler olanları eklenmiş. Hadi gelin temayı değiştirelim!
Template olarak better-docs kütüphanesini kullanmaya çalışalım. Öncelikle npm paketi olarak sunulan temanın kurulumunu yapalım.
npm install --save-dev better-docsKomutunu uyguladıktan sonra JSDoc ayarlarını tuttuğumuz dosyada opts objesine aşağıdaki gibi ekleme yapalım
"template": "node_modules/better-docs"ve tekrar dokümantasyonumuzda değişikliği gerçekleştirmek için komutumuzu çalıştırıyoruz
npm run doc
Ta-ta-ta-tam! Temamızı çok kolay bir şekilde değiştirmiş olduk 💯
Görüldüğü kolay bir şekilde dokümantasyonumuzu çıkarmış olduk. Daha fazla bilgi için JSDoc sayfasını ziyaret edebilirsiniz.
