Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- ScummVM
- Teknik yazar:
- b-gent
- Proje adı:
- Doxygen aracılığıyla kaynak kod dokümanlarını iyileştirme
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
Mevcut ScummVM API (kaynak kodu) belgeleri şu adreste yayınlanmıştır: https://doxygen.scummvm.org/modules.html
Maalesef birçok alanda eksiklikler var:
1) Hiçbir şekilde yapılandırılmamış, tüm bilgiler aynı seviyede.
2) C++ öğeleri tutarsız bir şekilde belgelenmiştir ve bazılarının hiç belgesi yoktur. Kurumun bu konuyu temel sorunlardan biri olarak belirttiğini görüyoruz.
3) Eski ve desteği sonlandırılmış içerikler çıkışta hâlâ gösteriliyor.
4) Doxygen etiketlemenin dili ve kullanımı daha tutarlı hale getirilmelidir. Bunun için bir kurallar grubuna ihtiyaç vardır. Bu kurallar, bu proje için gelecekteki bir doküman stil kılavuzu için temel oluşturabilir.
5) Bu sayfada kullanılan doxygen CSS'si, ScummVM web sitesine (https://www.scummvm.org) daha benzer hale getirilebilir.
Bu sorunların tümü Dokümanlar Sezonu projesi sırasında ele alınabilir.
Bu Belge Sezonu başvurusuna, önerdiğim bazı olası iyileştirmeleri göstermek için projede açtığım bir taslak PR eşlik ediyor: https://github.com/scummvm/scummvm/pull/2361 İçeriğiyle ilgili bazı ayrıntılar için ve farkı görmek üzere buradaki açıklamaya bakın.
PR'nin kapsamı kabaca aşağıdaki gibidir:
1) Şu anda potansiyel yeni katkıda bulunanlar ve genel olarak mevcut API dokümanlarını görüntüleyen herkes için en kafa karıştırıcı şeyin yapı eksikliği olduğunu düşünüyorum. Yapılandırılmış API belgelerinin kullanıma sunulması, belgenin okunabilirliğini, bulunabilirliğini ve sonuç olarak kullanılabilirliğini iyileştirir. Bu nedenle, PR'm "common" klasöründeki tüm başlık dosyalarına doxygen grupları ekler. Bu yeni yapı sayesinde, kullanıcılar işletim sistemiyle ilgili API'lerin belgelerini (ör.) gezinme menüsünde kolayca bulabilir.
2) Bu dokümanların oluşturulmasını sağlamak için yeni bir doxygen yapılandırma dosyası oluşturuldu.
3) Dokümanda kullanılan tüm bağlantıların tek kaynaklı olarak kullanılabileceği bir 'links.doxyfile' dosyası. Doxygen ile çalışırken kullanışlı bir mekanizmadır.
4) Değiştirilmiş bir doxygen CSS'si. Bu, şu anda başka bir açık kaynak projesinden alınmıştır ve yalnızca başlangıç noktasıdır. İdeal olarak, doxygen sayfasının görünümü ScummVM web sayfasıyla aşağı yukarı tutarlı olmalıdır.
PR'nin kapsamadığı ancak kesinlikle üzerinde çalışılması gereken konu, içeriğin kendisidir. Bununla, kodun belgelenmemiş, yeterince belgelenmemiş olan önemli kısımlarını veya kodun belgelerden kaldırılması gereken eski bölümlerini tanımlamayı kastediyorum. Projede daha önce çalışmadığım için bunu başarmak için bir mentordan rehberlik almamız gerekiyor.
Elbette, PR'den bir şey uygulayıp uygulamayacağımız kuruluşla yapacağımız görüşmeye bağlıdır. Hareketlerin sözlerden daha değerli olduğunu düşündüğüm için, uygulamada ne yapabileceğimi açıklamak yerine bunu göstermeye karar verdim.
Kuruluş, bu proje için aşağıdaki kaba zaman çizelgesini sağlamıştır: Hafta Ana görev Hafta 0 (14 Eylül'den önce) Teklif tartışması ve incelemeler Hafta 1 (14 Eylül) Doxygen derleme ayarı Hafta 2 (21 Eylül) Doxygen derlemesinin yenilenmesi (düşük öncelik) Hafta 3 (28 Eylül) Ortak kod - OSystem, FS, Veri Yapıları, Dize vb. Hafta 4 (5 Ekim) Ortak kod - Devam Hafta 5 (12 Ekim) Motorlar - Ortak kod ve örnek motor Hafta 6 (19 Ekim) Grafik Hafta 7 (26 Ekim) Ses Hafta 8 (2 Kasım) Video, Resimler Hafta 9 (9 Kasım) Arka uçlar - Platformlar, Grafikler, Etkinlikler Hafta 10 (23 Kasım) Arka uçlar - Devam Hafta 11 (30 Kasım) Proje özeti ve gönderimi
Tek önerim, daha önce de belirtildiği gibi yapı üzerinde çalışmaya başlamaktır. Bu işlem, doxygen derleme kurulumu (çoğunlukla zaten tamamlanmıştır) ve Doxygen teması yenileme ile birlikte 1. ve 2. haftalarda yapılabilir. Sonrasında, sorunları belirlemek ve doxsijen belgelerini iyileştirmek için mentorla farklı alanları tek tek incelemenin daha mantıklı olacağına katılıyorum.
Bu projenin standart uzunlukta olduğunu görüyorum ancak GSoD projesi tamamlandıktan sonra API dokümanlarıyla ilgili yapılabilecek başka iyileştirmeler olduğundan eminim. Örneğin, katkıda bulunanların ekledikleri kodu nasıl belgelemeleri gerektiğinin farkında olmaları için bir doküman stil kılavuzu oluşturup wiki'ye eklemek.
GSoD sona erdikten sonra bu tür görevlerde size yardımcı olmaktan memnuniyet duyarım. ScummVM'nin, API belgesinin yüksek kalitede ve kullanılabilirliğe sahip olmasını sağlayacak bir teknik yazarla çalışabileceğine eminim. Ayrıca, eklentilerle çalışmayla ilgili bir kılavuz oluşturma gibi gelecekte size yardımcı olabileceğim başka doküman projeleri olduğunu da görüyorum.