Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ScummVM
- Pisarz techniczny:
- b-gent
- Nazwa projektu:
- Ulepsz dokumentację kodu źródłowego za pomocą Doxygen
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Obecna dokumentacja interfejsu ScummVM API (kod źródłowy) jest opublikowana tutaj: https://doxygen.scummvm.org/modules.html
Niestety w wielu obszarach go brakuje:
1) Nie ma w nim praktycznie żadnej struktury, wszystkie informacje unoszą się na tym samym poziomie.
2) Elementy C++ są udokumentowane w sposób niespójny – niektóre z nich w ogóle nie są udokumentowane. Jest to jeden z głównych problemów organizacji.
3) W danych wyjściowych nadal wyświetlają się nieaktualne i wycofane treści.
4) Język i zastosowanie tagowania doxygen powinny być bardziej spójne. Potrzebny jest do tego zestaw reguł, które mogą posłużyć za podstawę przyszłego przewodnika po stylu dokumentacji dotyczącego tego projektu.
5) Kod CSS doxygen używany na tej stronie można ulepszyć, aby był bardziej podobny do witryny ScummVM: https://www.scummvm.org
Wszystkim tym problemom można pomóc w ramach projektu Sezon Dokumentów.
Do zgłoszenia do programu sezonu Dokumentów towarzyszy wersja robocza PR, którą otwieram w projekcie, aby zaprezentować ewentualne ulepszenia, które proponuję: https://github.com/scummvm/scummvm/pull/2361 W opisie znajdziesz szczegółowe informacje o tym, co zawiera, i jakie różnice mogą się od siebie różnić.
Mniej więcej na tym polega PR:
1) Myślę, że najbardziej niezrozumiały jest obecnie dla potencjalnych nowych współtwórców i zazwyczaj wszystkich, którzy przeglądają bieżący dokument interfejsu API, brak struktury. Wprowadzenie uporządkowanej dokumentacji interfejsu API poprawiłoby czytelność i łatwość wyszukiwania, a tym samym zwiększyłoby użyteczność zestawu dokumentów. Właśnie dlatego dział PR wprowadza grupy doxygen we wszystkich plikach nagłówka w folderze „common”. Dzięki tej nowej strukturze osoba, która chce znaleźć (na przykład) dokumentację interfejsu API związanego z systemem operacyjnym, może ją łatwo znaleźć w nawigacji.
2) Aby można było utworzyć tę dokumentację, został skonfigurowany nowy plik konfiguracji doxygen.
3) Plik „links.doxyfile”, z którego wszystkie linki używane w dokumentacji pochodzą z jednego źródła. Przydatny mechanizm pracy z doxygenem.
4) Zmodyfikowany doxygen CSS. Ten fragment pochodzi obecnie z innego projektu open source i jest tylko punktem wyjścia. Najlepiej, gdyby wygląd i działanie strony doxygen były mniej lub bardziej spójne ze stroną internetową ScummVM.
PR nie jest tu kwestia PR, ale zdecydowanie trzeba zająć się samą treścią. Chodzi o to, aby wskazać zasadnicze części kodu, które nie są udokumentowane, te, które nie są wystarczająco udokumentowane, lub nieaktualne części kodu, które należy usunąć z dokumentacji. Ponieważ nie pracowałam wcześniej w tym projekcie, potrzebujemy wskazówek mentora.
Oczywiście o tym, czy wdrożymy rozwiązania PR, należy omówić z organizacją. Pomyślałem, że czyny mówią głośniej niż słowa, więc postanowiłam pokazać, co potrafię, zamiast po prostu opisać to w aplikacji.
Organizacja przygotowała następujący ogólny harmonogram tego projektu: Tydzień 0 i przykładowy projekt graficzny / Tydzień01
Jedyną propozycją zmiany jest zacząć od opracowania struktury, o której już wspomnieliśmy. Można to zrobić w pierwszych i 2 tygodniach, dodając do tego konfigurację kompilacji doxygen (co jest już w dużej mierze wykonywane) i odświeżać skórę Doxygen. Potem zgadzam się, że najlepiej będzie, jeśli wspólnie z mentorem przeanalizują różne obszary, aby zidentyfikować problemy i ulepszyć dokumentację doksygenową.
Widzę projekt o standardowej długości, ale jestem pewny, że w dokumentacji interfejsu API można wprowadzić inne ulepszenia, które można wprowadzić po zakończeniu projektu GSoD. Można na przykład przygotować przewodnik dotyczący stylu dokumentacji i dodać go do witryny wiki, aby pokazać im, jak powinni udokumentować dodawany kod.
Chętnie pomogę w takich zadaniach po zakończeniu GSoD. Na pewno ScummVM może skorzystać z pomocy autora tekstu technicznego, który zadba o to, aby jego dokument API miał dobrą jakość i łatwość obsługi. Widzę też, że w przyszłości mogę pomóc Ci w innych projektach dokumentów, takich jak przewodnik na temat pracy z wtyczkami.