Flutter/Dart projeleri için dokümantasyon nasıl hazırlanır?

Az gittiniz, uz gittiniz, dere tepe düz gittiniz, şakır şakır, takır tukur kodları yazdınız ve iyi kötü bir proje ortaya çıkardınız.

İyi güzel de, malum, nefesler sayılı, veya daha büyük kariyer hedefleriniz var ve mevcut projeden uçmanın yollarını arıyorsunuz. Bunların hepsi olağan, olması gereken alkışlarla uğurlanmak için dokümantasyon yazmanız.

Bu konuları ilk yazan değilim, son da olmayacağım o yüzden yine her zamanki gibi kendime not niteliğinde bir yazı olduğundan eksikler içermektedir. https://pub.dev/packages/dartdoc paketinin açıklamalarını okurken aldığım notlardır, doğrudan ilgili sayfayı okumanızı tavsiye ederim. Bilginize.

dartdoc eklentisini/paketini kullanacağız: https://pub.dev/packages/dartdoc

Ben HTML bir dokümantasyon oluşturmak istediğim için:

dart pub global activate dartdoc

komutları yardımıyla kurulumu yaptım ve kurduktan sonra dartdoc ile oluşmasını sağladım.

Proje dizini içerisinde /doc/api/ klasörünün altına ayrıntılı bir dokümantasyon oluşturuldu.

Arama yapılabilir şekilde kullanmak için sayfaları localhost üzerinde yayınlamanız gerekmektedir:

Oluşan dokümantasyonu incelediğimizde eksik olan yerler olduğunu tespit ettim. Bunun sebebi bizim kodu yazarken otomatik dokümantasyon işlemi yapmak üzere dikkatli bir şekilde kod yazmamız olduğunu öğrendim.

Oluşan link yapısı aşağıdaki şekilde özetlenmiştir:

Örneğin /lib/ui/widgets/Buttons.dart dosyası için hazırladığı dokümantasyon ui-widget-buttons klasörünün içerisinde ve şu şekildedir:

Peki nasıl yazmamız gereklidir?

https://dart.dev/guides/language/effective-dart/documentation adresine ışınlandık 🙂

dartdoc /// ile yazılmış dokümantasyon yorumlarını dikkate almaktadır. Metodların, değişkenlerin, widgetların kısacası neyi dokümante etmemiz gerekiyorsa onun hemen üzerinde /// ile yorumumuzu yazmamız gerekmektedir.

En iyi kod, yorumsuz koddur, veya /// ardından gelen 1 satırlık bir cümle ile kendini izah eden unsurlardan oluşan koddur. Yorum 1 satırdan fazla tutuyorsa belki de aşağıdaki kod bloğu birden fazla parçaya bölünebilir durumdadır 🙂 O zaman önce bölelim, sonra yorumlarımızı yazalım.

Elimizden geleni yaptık ve 1 satırda ifade edemiyorsak aşağıdaki gibi yazalım:

/// Deletes the file at [path].
///
/// Throws an [IOError] if the file could not be found. Throws a
/// [PermissionError] if the file is present but could not be deleted.

Değişken, metod ve tipleri tanımlarken köşeli parantez ile belirtelim:

// Throws a [StateError] if ...
/// similar to [anotherMethod()], but ...

Bir sınıfa ait elemanı belirtirken SınıfAdı.ElemanAdı şeklinde kullanalım:

/// Similar to [Duration.inDays], but handles fractional days.

named constructor belirtmek için:

/// To create a point from polar coordinates, use [Point.polar()].

Dokümantasyona eklenmemesi gerekenleri @nodoc ile belirtiyoruz.

Örnek bir görüntü ile yazımızı bitiriyoruz:

Okuduğunuz için teşekkür ederim.

Bir cevap yazın

E-posta hesabınız yayımlanmayacak.