İçeriğe geç
Tüm projeler
AraçlarAçık kaynak

LiveDocGen: Canlı Yenilemeli C++ Dokümantasyon Sunucusu

Boost.Beast kullanan, özel bir C++ dokümantasyon üreticisi ve yerel HTTP sunucusu. Doxygen tarzı başlık (header) yorumlarını ayrıştırır, zaman damgası (timestamp) hash'leme yoluyla canlı yenileme özellikli bir web arayüzü sunar ve otomatik olarak HTML ile Markdown çıktıları üretir.

Kaynak kodu

Teknoloji yığını

Diller

Performans & metrikler

  • İmzasız dosyaları doğrudan I/O sınırında atlayarak devasa kod tabanlarının (codebases) anında ayrıştırılması
  • Lokalize string akışları ve std::stringstream tampon (buffer) yeniden kullanımı sayesinde minimum yığın (heap) parçalanması ve düşük bellek ayak izi
  • Tek iş parçacıklı asenkron I/O mimarisi, HTTP payload iletimleri sırasında kesinlikle bloklanma (blocking) yaşanmamasını sağlar

Neden geliştirdim?

Doxygen ve Sphinx inanılmaz derecede güçlü olsalar da, aktif geliştirme aşamasındaki hızlı ve lokalize API dokümantasyonu için genellikle hantal ve yavaş kalıyorlar. API sözleşmelerimi anında görselleştirebilmek için herhangi bir C++ projesine kolayca dahil edebileceğim bu hafif, hiper odaklı aracı geliştirdim. Belirli bir dosya imzasını zorunlu kılarak, ayrıştırıcının devasa üçüncü parti bağımlılık ağaçlarını akıllıca yoksaymasını sağladım. Dahili canlı yenileme yapan HTTP sunucusu sayesinde, kod yazıp kaydettiğim an, manuel olarak hiçbir derleme betiği çalıştırmadan formatlanmış dokümantasyonu ikinci ekranımda anında görebiliyorum.

Mimari & kararlar

Tamamen modern C++ ile yazılmış olan bu araç, özyineli (recursive) dizin taraması için std::filesystem'i, hafif bir yerel sunucu ayağa kaldırmak için ise Boost.Beast/Boost.Asio ağ yığınını kullanır. Ayrıştırma motoru, belirli etiketleri (\brief, \param, \warning) çıkarmak ve karşılık gelen C++ imzalarını (fonksiyonlar, makrolar, typedef'ler, değişkenler) doğrudan kod üzerinden anlamlandırmak için durumlu (stateful) bir metin tokenleştirici kullanır. Sunucu, tek iş parçacıklı asenkron bir bağlamda (net::io_context{1}) çalışır. Uzun süreli sorgulama (long-polling) yapan /version uç noktası, dinamik olarak enjekte edilen JavaScript aracılığıyla otomatik istemci tarafı UI yenilemelerini tetiklemek için dosya değiştirme zaman damgalarını hash'ler.

Temel özellikler

  1. 01Boost.Beast ve Boost.Asio altyapılı, sıfır konfigürasyonlu yerel HTTP sunucusu
  2. 02Üçüncü parti kütüphanelerin taranmasını agresif bir şekilde önlemek için özel bir dosya imzasıyla hedeflenmiş dosya ayrıştırma
  3. 03JS sorgulama ve işletim sistemi düzeyinde zaman damgası hash'leme yoluyla otomatik canlı yenilenen web arayüzü
  4. 04Doğrudan dosya sistemine eşzamanlı statik artifact üretimi (index.html ve index.md)
  5. 05Ağır derleyici arayüzlerine (compiler frontends) ihtiyaç duymadan fonksiyonlar, makrolar ve typedef'ler için satır içi (in-line) C++ imza çıkarma

Teknik değerlendirme

Bu araç, hızlı geliştirme döngüleri sırasında ham kaynak kod ile okunabilir dokümantasyon arasındaki boşluğu doldurmaktadır. Karmaşık XML yapılandırmalarıyla veya Doxyfile'larla uğraşmak yerine, sadece bir başlık (header) dosyasını etiketleyip standart blok yorumlar yazarak Boost destekli sunucunun temiz stillendirilmiş, canlı güncellenen bir HTML görünümü sunmasını sağlayabiliyorum. Kendi C++ sistem mühendisliği iş akışımı agresif bir şekilde hızlandırmak adına son derece uzmanlaşmış, düşük bağımlılıklı iç araçlar (internal tooling) yazma felsefemenin doğrudan bir kanıtıdır.