Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- ScummVM
- Teknik yazar:
- b-gent
- Projenin adı:
- Doxygen ile kaynak kodu belgelerini iyileştirin
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Mevcut ScummVM API (kaynak kodu) dokümanları şu adreste bulunmaktadır: https://doxygen.scummvm.org/modules.html
Maalesef bu özellik birçok alanda mevcut değil:
1) Neredeyse hiçbir yapısı yoktur, tüm bilgiler aynı düzeydedir.
2) C++ öğeleri, bazıları hiç belgelenmemiş olarak tutarsız bir şekilde belgelenmiş. Kurumun ana sorunlardan biri olarak bahsettiği bu durum.
3) Eski ve desteği sonlandırılmış içerik çıkışta görüntülenmeye devam etmektedir.
4) Doksijen etiketleme dili ve kullanımı daha tutarlı hale getirilmelidir. Bunun için bir dizi kurala ihtiyaç vardır. Bu kurallar, gelecekte bu proje için hazırlanmış bir belge stil rehberine temel oluşturabilir.
5) Bu sayfada kullanılan doxygen CSS, ScummVM web sitesine daha benzer olacak şekilde iyileştirilebilir: https://www.scummvm.org
Dokümanların Sezonu projesi sırasında tüm bu sorunlar çözülebilir.
Bu Sezona ait Dokümanlar uygulamasıyla birlikte, önerdiğim bazı olası iyileştirmeleri göstermek için projede açtığım bir taslak PR kodu yer alıyor: https://github.com/scummvm/scummvm/pull/2361 İçerikle ilgili bazı ayrıntılar ve farkları görmek için açıklamaya bakın.
Halkla ilişkiler (PR) kabaca şunları içerir:
1) Bence şu anda potansiyel yeni katkıda bulunanlar için en kafa karıştırıcı olan şey ve genellikle mevcut API belgesini görüntüleyen herkes için yapı eksikliği. Yapılandırılmış API belgelerinin kullanıma sunulması, doküman kümesinin okunabilirliğini, bulunabilirliğini ve sonuç olarak kullanılabilirliğini artırır. PR'min 'common' klasöründeki tüm üstbilgi dosyalarına doksijen grupları eklemesinin nedeni budur. Bu yeni yapıyla, OS ile ilgili API dokümanlarını (ör.) bulmak isteyen kullanıcılar gezinme bölümünde ilgili API'yi kolayca bulabilir.
2) Bu dokümanların oluşturulmasını sağlamak için yeni bir doxygen yapılandırma dosyası ayarlanır.
3) Doküman kümesinde kullanılan tüm bağlantıların tek kaynaklı olabileceği bir 'links.doxyfile' dosyası. Doksijen ile çalışırken faydalı bir mekanizma.
4) Değiştirilmiş bir doksijen CSS'si. Bu bilgi, şu anda başka bir açık kaynak projesinden alınmıştır ve yalnızca bir başlangıç noktasıdır. İdeal olarak, doksijen sayfasının görünümü ve izlenimi, ScummVM web sayfasıyla az ya da çok tutarlı olmalıdır.
Halkla ilişkiler ekibinde ele alınmasa da üzerinde çalışılması gereken konu içeriğin kendisi. Bununla, kodun belgelenmemiş önemli parçalarını, yeterince belgelenmemiş olanları veya belgelerden kaldırılması gereken eski kod parçalarını tanımlamak kastediyorum. Daha önce bu projede çalışmadığım için bunu başarmak için bir mentordan rehberlik almam gerekecek.
Tabii ki halkla ilişkiler departmanından herhangi bir şeyi uygulayıp uygulamayacağımız kuruluşla görüş alışverişine bağlıdır. Benim düşüncem, eylemlerin kelimelerden daha değerli olmasıdır. Bu yüzden, bunu uygulamada açıklamak yerine neler yapabileceğimi göstermeye karar verdim.
Kuruluş bu proje için şu yaklaşık zaman çizelgesini sunmuştur: 1. Hafta (1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta-1. Hafta) Teklif tartışması ve incelemesi 1. Hafta (9/14) Doxygen derleme kurulumu 2. Hafta (9/21) Doxygen dış görünümünün yenilenmesi (düşük öncelikli) 3. Hafta (9/28) Ortak kod - Ortak kod, 9/28 Hafta sonu
Tek önerim, daha önce de belirttiğim gibi yapı üzerinde çalışarak başlamaktır. Bu işlem, doksijen derleme kurulumuyla (büyük ölçüde önceden yapıldı) ve Doxygen cilt yenilemesiyle birlikte 1. ve 2. haftalarda yapılabilir. Daha sonra, sorunları belirlemek ve doksijen belgelerini iyileştirmek için mentorla farklı alanları tek tek ele almanın en mantıklı olduğu fikrine katılıyorum.
Bunu standart uzunlukta bir proje olarak görüyorum ancak GSoD projesi bittikten sonra API belgeleri konusunda yapılabilecek başka iyileştirmeler de olduğundan eminim. Örneğin, katkıda bulunanların ekledikleri kodu nasıl belgelemeleri gerektiğini bilmeleri için bir doküman stil kılavuzu oluşturup wiki'ye ekleyebilirsiniz.
GSoD bittikten sonra bu tür görevler konusunda seve seve yardımcı olurum. ScummVM'nin, API belgesinin kaliteli ve kullanışlı olmasını sağlayacak teknik yazarlarla çalışabileceğinden eminim. Gelecekte size yardımcı olabileceğim başka doküman projelerinin de olduğunu görüyorum. Örneğin, eklentilerle çalışma konusunda bir rehber oluşturmak.