Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- ScummVM
- Technischer Redakteur:
- b-gent
- Projektname:
- Quellcodedokumentation über Doxygen verbessern
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Die aktuelle ScummVM API-Dokumentation (Quellcode) ist hier veröffentlicht: https://doxygen.scummvm.org/modules.html
Leider fehlt es in vielen Bereichen:
1) Es gibt praktisch keine Struktur, alle Informationen befinden sich auf derselben Ebene.
2) C++-Elemente sind nicht einheitlich dokumentiert, einige davon gar nicht. Dies ist etwas, das das Unternehmen als eines der Hauptprobleme erwähnt.
3) In der Ausgabe werden immer noch veraltete Inhalte angezeigt.
4) Die Sprache und Verwendung von Doxygen-Tags sollte einheitlicher gestaltet werden. Dazu sind Regeln erforderlich, die als Grundlage für einen zukünftigen Styleguide für die Dokumentation dieses Projekts dienen könnten.
5) Das auf dieser Seite verwendete Doxygen-CSS könnte verbessert werden, damit es der ScummVM-Website ähnelt: https://www.scummvm.org
All diese Probleme können im Rahmen des Projekts „Season of Docs“ angegangen werden.
Diese Season of Docs-Anwendung wird von einem PR-Entwurf begleitet, den ich im Rahmen des Projekts geöffnet habe, um einige mögliche Verbesserungen zu demonstrieren, die ich vorschlagen würde: https://github.com/scummvm/scummvm/pull/2361 In der Beschreibung findest du Details zum Inhalt und einen Überblick über die Unterschiede.
Das umfasst ungefähr Folgendes:
1) Ich denke, das verwirrendste für potenzielle neue Mitwirkende und allgemein für alle, die sich die aktuellen API-Dokumente ansehen, ist der Mangel an Struktur. Die Einführung einer strukturierten API-Dokumentation würde die Lesbarkeit, Auffindbarkeit und somit die Nutzerfreundlichkeit des Doc-Sets verbessern. Deshalb werden in meiner PR Doxygen-Gruppen für alle Header-Dateien im Ordner „common“ eingeführt. Mit dieser neuen Struktur können Nutzer, die beispielsweise nach Dokumenten für eine API suchen, die sich auf das Betriebssystem bezieht, diese ganz einfach in der Navigation finden.
2) Eine neue Doxygen-Konfigurationsdatei wird eingerichtet, um die Erstellung dieser Dokumentation zu ermöglichen.
3) Eine Datei „links.doxyfile“, aus der alle im DocSet verwendeten Links stammen. Ein nützlicher Mechanismus bei der Arbeit mit Doxygen.
4) Ein modifiziertes Doxygen-CSS. Dieser wird derzeit aus einem anderen Open-Source-Projekt übernommen und ist nur ein Ausgangspunkt. Idealerweise sollte das Erscheinungsbild der Doxygen-Seite mehr oder weniger konsistent mit der ScummVM-Webseite sein.
Was die PR nicht abdeckt, aber unbedingt bearbeitet werden muss, sind die Inhalte selbst. Damit meine ich, die wesentlichen Codeteile zu identifizieren, die nicht dokumentiert sind, die nicht ausreichend dokumentiert sind oder die veralteten Codeteile, die aus der Dokumentation entfernt werden sollten. Da ich noch nie an dem Projekt gearbeitet habe, benötige ich die Unterstützung eines Mentors, um dies zu erreichen.
Ob wir etwas aus der PR implementieren, wird natürlich mit der Organisation besprochen. Ich war der Meinung, dass Taten mehr als Worte sagen, und habe beschlossen, zu zeigen, was ich kann, anstatt es nur in der Bewerbung zu beschreiben.
Das Unternehmen hat den folgenden groben Zeitplan für dieses Projekt angegeben: Wochen Hauptaufgabe Wochen 0 (vor dem 14. September) Diskussion und Bewertung des Vorschlags Wochen 1 (14. September) Doxygen-Build einrichten Wochen 2 (21. September) Doxygen-Skin aktualisieren (niedrige Priorität) Wochen 3 (28. September) Gemeinsamer Code – OSystem, FS, Datenstrukturen, Strings usw. Wochen 4 (5. Oktober) Gemeinsamer Code – fortgesetzt Wochen 5 (12. Oktober) Engines – gemeinsamer Code und Beispiel-Engine Wochen 6 (19. Oktober) Grafiken Wochen 7 (26. Oktober) Audio Wochen 8 (2. November) Video, Bilder Wochen 9 (9. November) Backends – Plattformen, Grafiken, Ereignisse Wochen 10 (23. November) Backends – fortgesetzt Wochen 11 (30. November) Projektzusammenfassung und ‑einreichung
Die einzige Änderung, die ich vorschlagen würde, ist, wie bereits erwähnt, zuerst an der Struktur zu arbeiten. Dies kann in den Wochen 1 und 2 zusammen mit der Doxygen-Build-Einrichtung (die bereits weitgehend abgeschlossen ist) und der Aktualisierung des Doxygen-Skins erfolgen. Danach ist es am sinnvollsten, die verschiedenen Bereiche einzeln mit dem Mentor durchzugehen, um Probleme zu identifizieren und die Doxygen-Dokumentation zu verbessern.
Ich sehe das als Projekt mit Standardlänge an, aber ich bin sicher, dass es noch weitere Verbesserungen im Zusammenhang mit der API-Dokumentation gibt, die nach Abschluss des GSoD-Projekts vorgenommen werden können. Sie können beispielsweise einen Dokumentations-Styleguide erstellen und ihn dem Wiki hinzufügen, damit Mitwirkende wissen, wie sie den hinzugefügten Code dokumentieren sollen.
Nach Abschluss der GSoD kann ich Ihnen gerne bei solchen Aufgaben helfen. Ich bin sicher, dass ScummVM einen technischen Redakteur gebrauchen könnte, der dafür sorgt, dass die API-Dokumentation von guter Qualität und Nutzerfreundlichkeit ist. Ich sehe auch, dass es weitere zukünftige Doc-Projekte gibt, bei denen ich Ihnen helfen könnte, z. B. die Erstellung einer Anleitung zur Arbeit mit Plug-ins.