Swift DocC ile Dokümantasyonun Temelleri
Günümüz yazılım geliştirme dünyasında, iyi dokümantasyonun önemi her geçen gün daha da artıyor. Kapsamlı ve anlaşılır dokümantasyon, sadece yazılımın sürdürülebilirliğini artırmakla kalmaz, aynı zamanda geliştiriciler arasındaki işbirliğini ve kodun anlaşılabilirliğini de büyük ölçüde iyileştirir.
Apple, Swift dilinde bu ihtiyacı karşılamak amacıyla DocC adında güçlü bir dokümantasyon aracı sunuyor. Bu yazıda, Swift DocC’nin temellerini, nasıl kullanılacağını ve projelerinizde nasıl en iyi şekilde faydalanabileceğinizi inceleyeceğiz.
Bu yazıda, sıfırdan uygulama geliştirip dokümantasyon eklemek yerine bir önceki yazım için oluşturduğum uygulamaya dokümantasyon ekleyeceğiz.
Docc Nedir?
Apple’ın açıklamasına göre, Markdown tabanlı metni Swift framework’leri ve paketleri için zengin dokümantasyona dönüştürür. Üzerinde çalışırken dokümantasyonu yayınlanmış haliyle önizleyebilir ve tamamlandığında bir web sitesinde barındırabilirsiniz.
DocC sözdizimi, geliştiriciye özgü dokümantasyon özellikleri için işlevsellik ekleyen özel bir Markdown çeşididir. Bu özellikler arasında semboller arası bağlantı, terim tanım listeleri, kod listeleri ve yan notlar bulunur. Kaynak kodunuza dokümantasyon işaretlemesi ekler, DocC ile derler ve API’leriniz için referans dokümantasyonu üretirsiniz. Ayrıca, DocC’nin içeriğinizi nasıl oluşturacağını belirten bir dizi yönerge ile birlikte dokümantasyon işaretlemesini kullanarak, geliştiricilere etkileşimli kodlama alıştırmalarıyla API’lerinizi nasıl kullanacaklarını öğreten adım adım eğitimler veya belirli teknolojileri ya da konuları açıklayan kapsamlı makaleler sunabilirsiniz.
Projede kullanımı
Projelerinizde dokümantasyon oluşturmak aslında düşündüğünüzden çok daha kolay. İstediğiniz fonksiyon, sınıf veya değişkenin üzerine üç eğik çizgi “///” ekleyerek başlayın ve istediğiniz açıklamaları yazın. Bu basit adım, kodunuzu hem daha anlaşılır hale getirir hem de ekip arkadaşlarınızın işini kolaylaştırır. Örneklere başlamadan size kolaylık sağlayacak bir arayüzü açmanızı tavsiye ederim.
Yukarıdaki adımları başarılı bir şekilde yaptıysanız aşağıdakine benzer bir görüntü ile karşılaşmış olmalısınız.
Başlayalım
Öncelikle yazıyı buradan sonra 2 bölüme ayırdım. İlk bölümde bir geliştiricinin kodu yazarken kolaylıkla ekleyebileceği açıklamalardan bahsedeceğim. İkinci bölümde ise dökümanımızı daha da genişletip sadece kodlardan bahsetmek yerine rehber şeklinde nasıl sunabileceğinizi göreceğiz.
Bölüm 1: Kod açıklamaları
Bu açıklamada, FavoriteJokeCell sınıfının ne işe yaradığını açıkladım.
Bu bölümde, property’lerin ne işe yaradığını açıklayan yorumlar ekledim.
Bu bölüm, FavoriteJokeCell sınıfının initializer'ını (başlatıcı metodunu) açıklıyor. Yorum, bu metodun ne yaptığı ve hangi parametreleri aldığı hakkında bilgi veriyor. Örneğin, viewModel verileri yönetmek için gereklidir ve jokes, hücrede gösterilecek şaka listesidir gibi.
- Parameters:
Bu keyword ile fonksiyon’un aldığı parametreleri belirtebiliriz. Geliştirici dökümana bakarken parametrenin ne işe yaradığı hakkında fikir sahibi olabilir.
Bu bölüm, numberOfRowsInSection computed property'nin ne yaptığını açıklıyor. Bu property, şaka listesinin kaç öğe içerdiğini döndürür. Ayrıca, örnek bir kullanım senaryosu gösteren bir kod bloğu içerir.
- Returns:
Bu keyword ile fonksiyon’un döndürdüğü bilgiyi belirtebiliriz. Geliştirici dökümana bakarken döndürülen değerin ne anlama geldiği hakkında fikir sahibi olabilir.```swift
```
Kod bloğunun başında ve sonunda belirtilir ve içerideki kodun Swift dilinde olduğunu belirtir. Örnek kod kullanımlarını burada belirtebilirsiniz.
Bu bölüm, cellForRowAt computed property'nin ne yaptığını açıklıyor. Bu property, tablo görünümünde kullanılacak olan UITableViewCell'i oluşturur ve döndürür. Ayrıca, bir ekran görüntüsü bağlantısı ve hücrenin hangi sınıf kullanılarak oluşturulduğunu belirtir. Kullanacağınız fotoğrafı projenize eklediğinizden emin olun.
Dökümanımız basit hatlarıyla hazır. Şimdi yapmamız gereken küçük bir adım kaldı.
Yukarıdaki adımları takip ederek Build Documentation yapıyorum. Artık elimizde aşağıdaki gibi bir döküman bulunuyor. Buradan detaylara giderek hazırladığımız açıklamaları görebilmekteyiz.
Bölüm 2: Dökümantasyon Sayfası
Bölüm 1'de basit bir şekilde kodlarımızı açıkladıktan sonra dökümantasyonu daha da detaylandırmaya başlayabiliriz. Bunun için öncelikle Documentation Catalog oluşturmamız gerekmektedir.
New File -> Documentation Catalog adımları ile yeni bir katalog oluşturuyorum.
Artık aşağıdaki gibi bir klasör oluşmuştur oldum.
SOLID-Practice.md isimli dosya ise benim anasayfam olacak. Geliştirici dökümanı ilk açtığımda bu sayfa ile karşılaşıyor. Dökümanda kullanacağım tüm kaynakları Resources içerisinde tutacağım. Bölüm 1'deki favoriteCell isimli fotoğrafı da Resources içerisine kaydettim.
# ``SOLID_Practice``
This project was created to practice implementing the SOLID principles in a simple iOS application.
## Overview
The project consists of 1 screen where users can view Chuck Norris jokes and add them to their favorites.
## Purpose
The main purpose of this project is to demonstrate the application of the SOLID principles in software development. While the project's functionality is minimal, the focus is on adhering to SOLID principles rather than building a fully functional application.
### Articles
@Links(visualStyle: detailedGrid) {
- <doc:UsageExample>
}
### Documentation
I have written a Medium article discussing the implementation of SOLID principles in this project. You can find the article [here](https://medium.com/appcent/swift-dilinde-solid-prensipleri-ve-projede-kullanımı-b6bcad7b70f3).
Additionally, you can refer to the accompanying PDF document for detailed notes on the SOLID principles applied in this project: [PDF](https://github.com/caliskanzafer/SOLID-Practice-Joke-App/blob/main/SOLID-Practice/solid-notes.pdf).
### Code Review
If you are interested in reviewing the code and observing violations of SOLID principles along with their corrections, please follow these steps:
- Navigate to the **main** branch to see the initial implementation.
- Check out the **refactor** branch to view the improved and refactored code.
###### Feedback
Your feedback is valuable to me! If you have any suggestions, questions, or comments, please feel free to reach out to me on [Twitter](https://twitter.com/zfrclskn_). Your input helps me improve as a developer and writer.
Thank you for your interest and happy coding!Yukarıdaki hazırladığım içerik ile anasayfamı tasarlamış oldum. Şimdi nasıl gözüktüğüne bakalım.
@Links , Swift’deki dokümantasyon yorumları içinde diğer belgelere, rehberlere veya örneklere bağlantı vermek için kullanılır.
Anasayfamda Usage Example isimli bir yazıya bağlantı verdiğim gözüküyor. Hadi bunu da oluşturalım.
En başta oluşturduğum Documentation Catalog içerisine yeni bir Article File oluşturup ismini UsageExample.md yapıyorum. Sonrasında tasarladığım belgenin kodlarını ve nasıl gözüktüğünü aşağıya bırakıyorum.
# Usage Example
This article explains how to use the application.
@Metadata {
@PageImage(
purpose: card,
source: coverimage,
alt:"cover image"
)
}
## Included Features
Name | Description
------------------| -------------------------------------
`New Joke` | Gets new joke
`Add Favorite` | Adds the joke to favorites
`Remove Favorite` | Removes the joke from favorites
### Hearing the new joke!
@Row {
@Column(size: 2) {
To hear the new joke, press the ***"New Joke"*** button marked with a green box.
}
@Column {
}
}
### Adding to Favorites
@Row {
@Column(size: 2) {
To add to favorite, press the ***"Add Favorite"*** button marked with a green box.
}
@Column {
}
}
### Removing from Favorites
@Row {
@Column(size: 2) {
To remove from favorite, press the ***"Remove Favorite"*** button marked with a green box.
}
@Column {
}
}
Dökümanın son haline bir bütün olarak bakalım
Sonuç olarak
Etkili bir dokümantasyon, sadece projeyi daha iyi anlamakla kalmaz, aynı zamanda takım içi işbirliğini güçlendirir ve projeye katkıda bulunmak isteyenler için değerli bir kaynak sağlar. Swift DocC ile dokümantasyon oluşturmanın bu temel ilkelerini uygulayarak, projelerinizi daha profesyonel ve kullanıcı dostu hale getirebilirsiniz.
Yazının sonuna geldik. Umarım bu rehber, dokümantasyon süreçlerinizi iyileştirmenize ve daha etkili hale getirmenize yardımcı olur. Keyifli kodlamalar!
Herhangi bir öneriniz, sorunuz veya yorumunuz varsa lütfen bana Twitter üzerinden ulaşmaktan çekinmeyin. Katkılarınız bir geliştirici ve yazar olarak gelişmeme yardımcı oluyor.
Bu yazıda kullanılan tüm yazılı, görsel içeriğe ve kod içeriğine buradan ulaşabilirsiniz.
İlginiz için teşekkürler, iyi kodlamalar!
