Ta strona zawiera szczegóły projektu technicznego do pisania w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ScummVM
- Specjalista ds. technicznych:
- b-gent
- Nazwa projektu:
- Ulepsz dokumentację kodu źródłowego za pomocą Doxygen
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Aktualna dokumentacja interfejsu API (kod źródłowy) ScummVM jest dostępna tutaj: https://doxygen.scummvm.org/modules.html
Niestety brakuje w niej wielu informacji:
1) Nie ma tu praktycznie żadnej struktury, wszystkie informacje są na tym samym poziomie.
2) Elementy C++ są dokumentowane w sposób niespójny, a niektóre z nich w ogóle nie są udokumentowane. Organizacja wymienia to jako jeden z głównych problemów.
3) W wyniku nadal wyświetlają się nieaktualne i nieużywane treści.
4) Język i wykorzystanie tagowania doxygen powinny być bardziej spójne. Potrzebny jest zestaw reguł, który mógłby posłużyć jako podstawa przyszłego przewodnika po stylu dokumentacji dla tego projektu.
5) Należy ulepszyć kod CSS doxygen używany na tej stronie, aby był bardziej podobny do kodu witryny ScummVM: https://www.scummvm.org
Wszystkie te problemy można rozwiązać podczas projektu Sezon na dokumenty.
Wraz z tą aplikacją na sezon Docs przesyłam projekt PR, który otworzyłem w ramach projektu, aby zademonstrować niektóre potencjalne ulepszenia, które proponuję: https://github.com/scummvm/scummvm/pull/2361 W opisie znajdziesz szczegółowe informacje o zawartości i różnicach.
Oto, co obejmuje PR:
1) Uważam, że najbardziej mylące dla potencjalnych nowych autorów i w ogóle dla wszystkich, którzy czytają obecną dokumentację interfejsu API, jest brak struktury. Wprowadzenie uporządkowanej dokumentacji interfejsu API zwiększy czytelność i łatwość wyszukiwania, a w rezultacie – użyteczność dokumentu. Dlatego mój PR wprowadza grupy doxygen do wszystkich plików nagłówka w folderze „common”. Dzięki nowej strukturze użytkownicy, którzy chcą znaleźć dokumenty dotyczące interfejsów API związanych z systemem operacyjnym, mogą łatwo je znaleźć w menu nawigacyjnym.
2) Aby umożliwić tworzenie tej dokumentacji, skonfigurowano nowy plik konfiguracji doxygen.
3) plik „links.doxyfile”, z którego można pobrać wszystkie linki używane w całym zestawie dokumentów. Przydatny mechanizm podczas pracy z doxygen.
4) Zmodyfikowany arkusz CSS doxygen. Ta wersja została pobrana z innego projektu open source i stanowi tylko punkt wyjścia. Optymalny wygląd i sposób działania strony doxygen powinien być taki sam jak na stronie internetowej ScummVM.
PR nie obejmuje treści, ale zdecydowanie trzeba popracować nad nimi. Chodzi mi o to, aby zidentyfikować najważniejsze części kodu, które nie są udokumentowane, te, które nie są wystarczająco udokumentowane, lub te, które nie są wystarczająco udokumentowane, lub te, które powinny zostać usunięte z dokumentacji. Ponieważ nie pracowałam wcześniej nad tym projektem, potrzebuję wskazówek mentora.
Oczywiście to, czy wprowadzimy jakieś zmiany na podstawie opinii publicznej, zależy od organizacji. Uznałam, że czyny mówią więcej niż słowa, więc zamiast opisywać swoje umiejętności w podaniu, postanowiłam pokazać, co potrafię.
Organizacja podała przybliżony harmonogram tego projektu:Tydzień Główne zadanie Tydzień 0 (przed 14 września) Rozmowa i sprawdzanie propozycji Tydzień 1 (14 września) Konfigurowanie kompilacji Doxygen Tydzień 2 (21 września) Aktualizacja skórki Doxygen (niski priorytet) Tydzień 3 (28 września) Kod wspólny – system operacyjny, system plików, struktury danych, ciągi tekstowe itp. Tydzień 4 (5 października) Kod wspólny – kontynuacja Tydzień 5 (12 października) Silniki – kod wspólny i silnik przykładowy Tydzień 6 (19 października) Grafika Tydzień 7 (26 października) Dźwięk Tydzień 9 (9 listopada) Backendy – platformy, grafika, zdarzenia Tydzień 10 (23 listopada) Backendy – kontynuacja Tydzień 11 (30 listopada) Podsumowanie projektu i zgłoszenie
Jedyną zmianą, którą proponuję, jest rozpoczęcie pracy od struktury, jak już wspomniano. Można to zrobić w pierwszym i drugim tygodniu, wraz z konfiguracją budowy doxygenu (w większości już przeprowadzaną) oraz odświeżeniem skóry. Zgadzam się, że najlepiej jest przejrzeć po kolei różne obszary z mentorem, aby zidentyfikować problemy i ulepszyć dokumentację doxygen.
To projekt o standardowej długości, ale jestem przekonany, że po zakończeniu projektu GSoD można wprowadzić jeszcze inne ulepszenia dotyczące dokumentacji interfejsu API. Możesz na przykład opracować przewodnik stylów dokumentacji i dodać go do wiki, aby autorzy wiedzieli, jak dokumentować dodawany kod.
Chętnie pomogę Ci w takich zadaniach po zakończeniu GSoD. Jestem przekonany, że ScummVM może potrzebować osoby, która zajmie się dokumentacją techniczną i zadba o to, aby była ona wysokiej jakości i łatwo dostępna. Widzę też, że w przyszłości mogę Ci pomóc w przygotowaniu innych dokumentów, np. przewodnika po pracy z wtyczkami.