Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- ScummVM
- Pisarz techniczny:
- b-gent
- Nazwa projektu:
- Ulepszanie dokumentacji kodu źródłowego za pomocą Doxygen
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Bieżącą dokumentację interfejsu ScummVM API (kod źródłowy) opublikowano tutaj: https://doxygen.scummvm.org/modules.html
Niestety brakuje ich w wielu obszarach:
1) Nie ma w nim praktycznie żadnej struktury, wszystkie informacje unoszą się na tym samym poziomie.
2) Elementy C++ są dokumentowane niespójnie, a niektóre w ogóle nie są udokumentowane. Jest to jeden z głównych problemów organizacji.
3) Nieaktualne i wycofane treści nadal są wyświetlane w danych wyjściowych.
4) Język i stosowanie tagowania doxygen powinny być bardziej spójne. Potrzebny jest do tego zestaw reguł, które mogą być podstawą przyszłego przewodnika po stylach dokumentacji dotyczącej tego projektu.
5) Kod CSS doxygen użyty na tej stronie można ulepszyć, aby był bardziej podobny do witryny ScummVM: https://www.scummvm.org
Wszystkie te problemy można rozwiązać w ramach projektu Sezon Dokumentów.
Do zgłoszenia do programu Sezon Dokumentów jest dołączona wersja robocza odpowiedzi PR, którą otworzyłam w ramach projektu, aby zaprezentować proponowane przeze mnie potencjalne ulepszenia: https://github.com/scummvm/scummvm/pull/2361 W opisie znajdziesz szczegółowe informacje o zawartości i różnice.
Mniej więcej na tym polega PR:
1) Myślę, że to, co obecnie najbardziej niezrozumiałe dla potencjalnych nowych współtwórców, a przeważnie dla wszystkich osób przeglądających bieżący dokument interfejsu API, polega na braku struktury. Wprowadzenie uporządkowanej dokumentacji interfejsu API zwiększyłoby czytelność i możliwość znalezienia tego zestawu, a tym samym jego użyteczność. Dlatego PR wprowadza grupy doxygen do wszystkich plików nagłówkowych w folderze „common”. Dzięki tej nowej strukturze osoba, która chce na przykład znaleźć dokumentację interfejsu API związanego z systemem operacyjnym, może ją łatwo znaleźć w menu nawigacyjnym.
2) Aby umożliwić utworzenie tej dokumentacji, skonfigurowano nowy plik konfiguracji doxygen.
3) Plik „links.doxyfile”, z którego wszystkie linki używane w tym zestawie dokumentów mogą pochodzić z jednego źródła. Przydatny mechanizm przy pracy z doxygenem.
4) Zmodyfikowany kod CSS doxygen. Ta koncepcja jest obecnie zaczerpnięta z innego projektu open source i stanowi jedynie punkt wyjścia. Wygląd i działanie strony doxygen powinny być mniej lub bardziej spójne ze stroną internetową ScummVM.
PR nie jest tu poruszany, ale zapewne wymaga dopracowania samej treści. Chodzi mi o zidentyfikowanie zasadniczych części kodu, które nie są udokumentowane, tych, które nie są wystarczająco udokumentowane, lub nieaktualnych części kodu, które należy usunąć z dokumentacji. Nie brałem(-am) jeszcze udziału w tym projekcie, więc do realizacji tego projektu będą potrzebne wskazówki od mentora.
Oczywiście o tym, czy wdrożymy jakieś rozwiązania PR, należy omówić z organizacją. Pomyślałam, że działania mówią głośniej niż słowa, więc postanowiłam pokazać, co potrafię, zamiast opisywać je w aplikacji.
Organizacja przygotowała następujący ogólny harmonogram dla tego projektu: Grafika: 0, 0, 1 tydzień i przykład.
Jedyną propozycją zmiany jest rozpoczęcie pracy nad strukturą, o czym już wspomnieliśmy. Można to zrobić w pierwszych i 2 tygodniach, łącznie z konfiguracją kompilacji doxygenu (co jest już w większości już realizowanym) i odświeżaniu skóry z użyciem Doxygen. Później uważam, że najsensowniejsze jest przejście przez poszczególne etapy z mentorem, aby zidentyfikować problemy i ulepszyć dokumentację doksygenu.
Widzę projekt o standardowej długości, ale wiem, że po zakończeniu projektu GSoD można wprowadzić inne ulepszenia związane z dokumentacją interfejsów API. Można na przykład wymyślić przewodnik po stylu dokumentacji i dodać go do witryny wiki, aby współtwórcy wiedzieli, jak udokumentować dodawany kod.
Chętnie pomogę w takich zadaniach po zakończeniu GSoD. Na pewno firma ScummVM powinna skorzystać z pomocy autora tekstu technicznego, który dopilnuje, aby jego dokument API miał wysoką jakość i łatwość obsługi. Widzę też, że mogę pomóc Ci w innych projektach w przyszłości, na przykład o utworzeniu przewodnika na temat pracy z wtyczkami.