Bu doküman kütüphaneye katkıda bulunanlar için Doxygen yorum standardını, yerel build adımlarını ve GitLab Pages entegrasyonunu açıklar.

1. Araç Zinciri

include/sdl_painter/*.h   →  Doxygen  →  HTML (public/)
doc/*.md                  →  Doxygen  →  HTML (public/)
                                           ↓
                                    GitLab Pages
                              https://<namespace>.gitlab.io/<repo>/

Doxygen iki kaynağı birleştirir: header yorumları (API referansı) ve doc/ markdown dosyaları (rehberler, diyagramlar). Sonuç tek bir HTML sitesidir.

Mermaid diyagramları Doxygen'in HTML çıktısında güncel Doxygen sürümlerinde (≈1.10+) native olarak render edilir: `mermaid blokları <pre class="mermaid"> içine sarılır ve sayfaya CDN üzerinden mermaid.js enjekte edilir. CI'daki docs job'u bu nedenle Ubuntu'nun apt deposundaki (donmuş, eski) paket yerine Doxygen'in resmi Linux binary'sini indirir. Eski/donmuş Doxygen sürümleriyle (apt'tan gelen gibi) diyagramlar düz kaynak kod bloku olarak görünür — bu durumda doc/*.md dosyaları yine de GitLab/GitHub markdown viewer'ında okunabilir kalır.

2. Kurulum (ilk seferinde)

doxygen-awesome-css submodule'ü ekle

git submodule add \
  https://github.com/jothepro/doxygen-awesome-css.git \
  third_party/doxygen-awesome-css
git commit -m "chore: doxygen-awesome-css submodule eklendi"

Klonlama sırasında submodule'ü de çekmek için:

git clone --recurse-submodules <repo-url>
# Veya mevcut klonda:
git submodule update --init

GitLab CI'da GIT_SUBMODULE_STRATEGY: recursive zaten tanımlı; ek yapılandırma gerekmez.

3. Yerel Build

# CMake configure (bir kere yeterli — normal build ile aynı komut)
cmake --preset linux-debug
 
# Doxygen çalıştır
cmake --build --preset linux-debug --target sdlpainter_docs
 
# Tarayıcıda aç
xdg-open build/linux-debug/docs/public/index.html   # Linux
start build\linux-debug\docs\public\index.html       # Windows

Doxygen kurulu değilse CMake sdlpainter_docs hedefini tanımlamaz (projenin build'ini engellemez). Kurulum:

# Ubuntu / Debian
sudo apt install doxygen graphviz
 
# macOS
brew install doxygen graphviz
 
# Windows (winget)
winget install doxygen.doxygen
winget install graphviz.graphviz

4. Ne Belgelenmeli, Ne Belgelenmemeli

Kapsam	Kural
`include/sdl_painter/*.h` — tüm `public` üyeler	`@brief` zorunlu; parametreler ve dönüş değeri belgelenmeli
`include/sdl_painter/*.h` — sınıf/struct tanımı	Sınıf düzeyi blok (`/// @brief` + genel davranış açıklaması) zorunlu
`src/tessellator.h`, `src/render_batcher.h` (internal)	`@brief` yazılabilir; Doxygen çıktısına girmez (`EXCLUDE_PATTERNS` kapsar)
`private` metodlar	Gerekmedikçe yorum yazma — iyi isimlendirilmiş kod yeterli
Implementasyon (`*.cpp`)	Sadece neden kısmı için satır içi yorum; Doxygen çıktısına girmez

Kural: "Bu yorumu silsem başka bir geliştirici kayıptan zarar görür mü?" Cevap hayırsa yorum yazma.

5. Yorum Formatı

Tüm yorumlar /// üçlü slash ile yazılır. /** */ blok formatı kullanılmaz (Google Style tutarlılığı için).

5.1 Temel Yorum Bloku

 
static std::vector<Vertex> TessellateFilledCircle(float cx, float cy,
                                                  float radius);

5.2 Kullanılan Etiketler

Etiket	Ne zaman
`@brief`	Her public üyede zorunlu — tek satır özet
`@param name`	Her parametre için; ismi ve beklenen değer aralığını yaz
`@return`	Void dışı her fonksiyonda; hata durumu dahil
`@note`	Beklenmedik davranış, önemli kısıtlama, sözleşme
`@warning`	Yanlış kullanım crash / tanımsız davranış yaratıyorsa
`@code` / `@endcode`	Kullanım örneği (birden fazla satırsa)
`@see`	İlgili başka sınıf/metod (opsiyonel)
`@since`	API'ye faz bazlı eklendiyse (örn. `@since Phase 4`)

@todo ve @deprecated repo içinde kullanılmaz; bunlar ADR veya issue tracker'a aittir.

5.3 Sınıf Düzeyi Blok

class Image {

5.4 Enum Değerleri

 
enum class RendererBackend {
  kOpenGL,  
  kVulkan,  
};

Satır sonu ///< formatı Doxygen'de enum değerlerine yorum ekler.

5.5 <tt>@param</tt> İçin Birim ve Aralık Kuralı

Belirsizlik yaratabilecek her parametrede birim veya aralık belirt:

// İyi:
 
// Kötü (neyi belirtmiyor?):

6. Sık Yapılan Hatalar

6.1 @brief'i Tekrar Etmek

// Kötü: imza zaten bunu söylüyor
void DrawRect(float x, float y, float w, float h);
 
// İyi: imzanın söylemediğini ekle
void DrawRect(float x, float y, float w, float h);

6.2 Implementation Detayını Public Yoruma Koymak

// Kötü: kullanıcı bunu bilmek zorunda değil
void DrawRect(float x, float y, float w, float h);
 
// İyi: davranış sözleşmesi
void DrawRect(float x, float y, float w, float h);

6.3 Her Şeye Yorum Yazmak

// Kötü: gürültü
int32_t Width() const { return mWidth; }
 
// İyi: getter'lar öz açıklayıcı, yorum gereksiz
int32_t Width() const { return mWidth; }

7. WARN_IF_UNDOCUMENTED

Doxyfile.in içinde WARN_IF_UNDOCUMENTED = YES ayarlıdır. Bu, @brief eksik olan her public üye için Doxygen'in uyarı üretmesi anlamına gelir. CI pages job'u bu uyarıları stderr'e yazar; şimdilik build'i kırmaz (uyarı ≠ hata) ama gözden geçirilmeli.

İleride katı hale getirmek için Doxyfile.in'de:

WARN_AS_ERROR = YES   # Tüm uyarıları hata say → CI job başarısız olur
# veya daha seçici:
WARN_AS_ERROR = FAIL_ON_WARNINGS

8. GitLab Pages

pages CI job'u yalnızca default branch (main) üzerinde çalışır. Her merge sonrası dokümantasyon otomatik güncellenir.

Yayınlanan adres:

https://<gitlab-namespace>.gitlab.io/<repo-name>/

Proje henüz public değilse GitLab Pages ayarlarında **"Everyone"** erişimi verilmesi gerekebilir (Settings → General → Visibility → Pages).

9. Doküman Türleri ve Sorumlulukları

include/sdl_painter/*.h   ← API referansı (Doxygen)     Kim: kodu yazan
doc/hizli-baslangic.md    ← Kullanım rehberi (Markdown) Kim: kodu yazan
doc/mimari-genel-bakis.md ← Mimari (Markdown+Mermaid)   Kim: mimar / kıdemli
doc/akislar.md            ← Akışlar (Markdown+Mermaid)  Kim: mimar / kıdemli
adr/                      ← Karar gerekçeleri (ADR)     Kim: karar veren

İki belge türü birbirinin yerini tutmaz:

Doxygen yorumları → "Bu metod ne yapar, nasıl çağrılır?"
doc/ rehberleri → "Bu bileşen neden var, büyük resimde nerede durur?"

10. İlgili Dosyalar

Dosya	Rol
`cmake/Doxyfile.in`	Doxygen şablonu (CMake değişkenleri ile konfigure edilir)
`cmake/Docs.cmake`	`sdlpainter_docs` CMake hedefini tanımlar
`CMakeLists.txt`	`SDLPAINTER_BUILD_DOCS` option
`.gitlab-ci.yml`	`pages` job — main branch'te GitLab Pages'e yayınlar
`third_party/doxygen-awesome-css/`	Tema submodule'ü (git submodule add ile eklenir)