Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.
Ringkasan proyek
- Organisasi open source:
- ScummVM
- Penulis teknis:
- b-gent
- Nama proyek:
- Tingkatkan dokumentasi kode sumber melalui Doxygen
- Durasi proyek:
- Durasi standar (3 bulan)
Project description
Dokumentasi ScummVM API (kode sumber) saat ini dipublikasikan di sini: https://doxygen.scummvm.org/modules.html
Sayangnya, prinsip ini masih kurang di banyak aspek:
1) Praktis tidak ada struktur, semua informasi mengambang pada tingkat yang sama.
2) Elemen C++ didokumentasikan secara tidak konsisten dan beberapa di antaranya tidak didokumentasikan sama sekali. Hal ini adalah sesuatu yang disebutkan organisasi sebagai salah satu masalah utama.
3) Konten usang dan tidak digunakan lagi masih ditampilkan di output.
4) Bahasa dan penggunaan pemberian tag doksigen harus dibuat lebih konsisten. Diperlukan serangkaian aturan untuk hal ini, sesuatu yang dapat menjadi dasar untuk panduan gaya dokumentasi di masa mendatang untuk proyek ini.
5) CSS doxygen yang digunakan pada halaman ini dapat ditingkatkan agar lebih mirip dengan situs ScummVM: https://www.scummvm.org
Semua masalah ini dapat ditangani selama Project Musim Dokumen.
Aplikasi Season Dokumen ini disertai dengan draf PR yang saya buka dalam project untuk menunjukkan beberapa potensi peningkatan yang saya usulkan: https://github.com/scummvm/scummvm/pull/2361 Lihat deskripsinya di sana untuk mengetahui beberapa detail tentang isinya dan untuk melihat perbedaannya.
Berikut ini hal-hal yang terlibat dalam PR:
1) Saya pikir apa yang paling membingungkan saat ini bagi calon kontributor baru, dan umumnya setiap orang yang melihat dokumen API saat ini, adalah kurangnya struktur. Memperkenalkan dokumentasi API terstruktur akan meningkatkan keterbacaan, kemudahan ditemukan, dan, akibatnya, kegunaan dokumen. Itu sebabnya PR saya memperkenalkan grup doksigen ke semua file {i>header<i} di folder 'common'. Dengan struktur baru ini, jika seseorang ingin mencari dokumen untuk API terkait OS (misalnya), ia dapat dengan mudah menemukannya di navigasi.
2) File konfigurasi doksigen baru disiapkan untuk memungkinkan pembuatan dokumentasi ini.
3) File 'links.doxyfile' tempat semua tautan yang digunakan di seluruh dokumen dapat dijadikan satu sumber. Mekanisme yang berguna saat bekerja dengan doksigen.
4) CSS doksigen yang dimodifikasi. Saat ini, proses ini diambil dari project open source lain dan hanya merupakan titik awal. Idealnya, tampilan dan nuansa halaman doxygen harus kurang lebih sama dengan halaman web ScummVM.
Yang tidak dicakup oleh PR, tetapi harus diperbaiki adalah konten itu sendiri. Maksud saya adalah mengidentifikasi bagian penting dari kode yang tidak didokumentasikan, bagian yang tidak didokumentasikan secara memadai, atau bagian kode usang yang harus dihapus dari dokumentasi. Karena saya belum pernah mengerjakan proyek ini sebelumnya, bimbingan dari seorang mentor akan diperlukan untuk mencapai hal ini.
Tentu saja, terserah diskusi dengan organisasi untuk menerapkan apa pun dari PR. Ide saya adalah bahwa tindakan berbicara lebih keras daripada kata-kata, jadi saya memutuskan untuk menunjukkan apa yang bisa saya lakukan, bukan sekadar mendeskripsikannya di aplikasi.
Organisasi telah menyediakan rentang waktu kasar berikut untuk project ini: Minggu Tugas utama Minggu 0 (Sebelum 9/14) Diskusi & tinjauan proposal Minggu 1 (14/9) Penyiapan build Doxygen Minggu 2 (21/9) Refresh skin Doxygen (prioritas rendah) Minggu 3 (9/28) Minggu, Kode umum - OSystem, FS, Struktur Data, String
Satu-satunya perubahan yang akan saya usulkan adalah memulai dengan mengerjakan struktur, seperti yang telah disebutkan. Hal ini dapat dilakukan di minggu 1 & 2, bersama dengan pengaturan build doxygen (yang sebagian besar sudah dilakukan) dan refresh kulit Doxygen. Setelah itu, saya setuju bahwa paling masuk akal untuk memeriksa berbagai bidang satu per satu dengan mentor untuk mengidentifikasi masalah dan meningkatkan dokumentasi doxygen.
Saya melihat ini sebagai project standar, tetapi saya yakin ada peningkatan lain terkait dokumentasi API yang bisa dilakukan setelah project GSoD selesai. Misalnya, membuat panduan gaya dokumentasi dan menambahkannya ke wiki, sehingga kontributor mengetahui bagaimana mereka harus mendokumentasikan kode yang mereka tambahkan.
Saya akan dengan senang hati membantu tugas seperti ini setelah GSoD selesai. Saya yakin ScummVM bisa menggunakan seorang penulis teknis yang akan memastikan bahwa dokumen API-nya berkualitas dan bermanfaat. Saya juga dapat melihat bahwa ada proyek dokumen lain di masa mendatang yang dapat saya bantu lakukan, seperti membuat panduan tentang cara bekerja dengan plugin.