이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- ScummVM
- 기술 문서 작성자:
- b-gent
- 프로젝트 이름:
- Doxygen을 통한 소스 코드 문서 개선
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
최신 ScummVM API(소스 코드) 문서는 여기(https://doxygen.scummvm.org/modules.html)에 게시됩니다.
안타깝게도 많은 부분에서 이 기술이 부족합니다.
1) 실질적으로 구조가 없고 모든 정보가 동일한 레벨에 떠 있습니다.
2) C++ 요소가 일관되지 않게 문서화되어 있으며 일부 요소는 전혀 문서화되어 있지 않습니다. 이는 조직에서 주요 문제 중 하나로 언급하는 사항입니다.
3) 오래되고 지원 중단된 콘텐츠가 출력에 계속 표시됩니다.
4) Doxygen 태그 지정의 언어 및 사용이 더 일관되게 만들어야 합니다. 이를 위한 규칙 집합이 필요하며, 이 규칙 집합은 향후 이 프로젝트의 문서 스타일 가이드의 기반이 될 수 있습니다.
5) 이 페이지에서 사용되는 doxygen CSS를 ScummVM 웹사이트(https://www.scummvm.org)와 더 유사하게 개선할 수 있습니다.
이러한 모든 문제는 Season of Docs 프로젝트 기간에 해결할 수 있습니다.
이번 Season of Docs 애플리케이션에는 제가 제안하는 몇 가지 잠재적인 개선사항을 보여주기 위해 프로젝트에서 공개한 PR 초안이 함께 제공됩니다. https://github.com/scummvm/scummvm/pull/2361 포함된 내용 및 차이점을 확인하려면 해당 설명을 참조하세요.
이는 대략 PR과 관련이 있습니다.
1) 현재 신규 참여자와 일반적으로 현재 API 문서를 보는 모든 사용자에게 가장 혼란스러운 점은 구조가 없다는 것입니다. 구조화된 API 문서를 도입하면 가독성, 검색 가능성, 그리고 결과적으로 문서 세트의 사용성이 개선됩니다. 그래서 PR이 'common' 폴더의 모든 헤더 파일에 doxygen 그룹을 소개합니다. 이 새로운 구조를 사용하면 OS 관련 API 문서를 찾고자 하는 사용자가 탐색 메뉴에서 쉽게 찾을 수 있습니다.
2) 이 문서를 빌드할 수 있도록 새 doxygen 구성 파일이 설정됩니다.
3) 'links.doxyfile' 파일: 이 파일에서 문서 세트 전반에 사용된 모든 링크를 단일 소스로 가져올 수 있습니다. doxygen을 다룰 때 유용한 메커니즘입니다.
4) 수정된 doxygen CSS 현재는 다른 오픈소스 프로젝트에서 가져온 것으로 시작에 불과합니다. Doxygen 페이지의 모양새는 ScummVM 웹페이지와 어느 정도 일관성이 있어야 합니다.
PR에서 다루지 않지만 반드시 처리해야 하는 사항은 콘텐츠 자체입니다. 즉, 문서화되지 않은 코드의 필수 부분, 문서화되지 않은 코드의 필수 부분, 문서에서 삭제해야 하는 오래된 코드 부분을 식별하는 것입니다. 이전에 이 프로젝트에서 작업한 적이 없으므로 이를 달성하려면 멘토의 안내가 필요합니다.
물론 PR에서 제안한 내용을 구현할지는 조직과의 논의에 따라 달라집니다. '말보다 행동이 중요하다'는 생각으로 애플리케이션에서 설명하는 대신 내가 할 수 있는 일을 보여주기로 했습니다.
조직에서 이 프로젝트에 대한 대략적인 타임라인을 다음과 같이 제공했습니다. 주차 주요 작업 주 0 (9월 14일 이전) 제안서 논의 및 검토 주 1 (9월 14일) Doxygen 빌드 설정 주 2 (9월 21일) Doxygen 스킨 업데이트 (우선순위 낮음) 주 3 (9월 28일) 공통 코드 - OSystem, FS, 데이터 구조, 문자열 등 주 4 (10월 5일) 공통 코드 - 계속 주 5 (10월 12일) 엔진 - 공통 코드 및 샘플 엔진 주 6 (10월 19일) 그래픽 주 7 (10월 26일) 오디오 주 8 (11월 2일) 동영상, 이미지 주 9 (11월 9일) 백엔드 - 플랫폼, 그래픽, 이벤트 주 10 (11월 23일) 백엔드 - 계속 주 11 (11월 30일) 프로젝트 요약 및 제출
제안하는 유일한 변경사항은 이미 언급한 대로 구조를 먼저 작업하는 것입니다. 이는 Doxygen 빌드 설정 (대부분 이미 완료됨) 및 Doxygen 스킨 새로고침과 함께 1주차 및 2주차에 수행할 수 있습니다. 이후에는 멘토와 함께 다양한 영역을 하나씩 살펴보고 문제를 파악하고 doxygen 문서를 개선하는 것이 가장 좋다는 데 동의합니다.
표준 길이의 프로젝트로 보이지만 GSoD 프로젝트가 완료된 후 API 문서와 관련하여 다른 개선사항을 적용할 수 있을 것입니다. 예를 들어 문서 스타일 가이드를 작성하여 위키에 추가하면 참여자가 추가하는 코드를 어떻게 문서화해야 하는지 알 수 있습니다.
GSoD가 끝난 후에는 이러한 작업을 기꺼이 도와드리겠습니다. ScummVM은 API 문서의 품질과 사용성을 보장할 기술 작가를 사용할 수 있을 것입니다. 플러그인을 사용하는 방법에 관한 가이드 작성 등 향후 도움을 드릴 수 있는 다른 문서 프로젝트도 있습니다.