Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- ScummVM
- Redator técnico:
- b-gent (link em inglês)
- Nome do projeto:
- Melhorar a documentação do código-fonte com o Doxygen
- Duração do projeto:
- Duração padrão (três meses)
Project description
A documentação atual da API ScummVM (código-fonte) está publicada aqui: https://doxygen.scummvm.org/modules.html
Infelizmente, ele está faltando em muitas áreas:
1) Praticamente não há estrutura, todas as informações estão flutuando no mesmo nível.
2) Os elementos C++ são documentados de maneira inconsistente e alguns deles não são documentados. Isso é algo que a organização menciona como um dos principais problemas.
3) Conteúdo desatualizado e descontinuado ainda aparece na saída.
4) A linguagem e o uso de marcação do doxygen precisam ser mais consistentes. Um conjunto de regras é necessário para isso, algo que possa ser a base para um guia de estilo de documentação futura para este projeto.
5) O CSS do doxygen usado nesta página pode ser melhorado para torná-lo mais semelhante ao site do ScummVM: https://www.scummvm.org
Todos esses problemas podem ser resolvidos durante o projeto sobre a Temporada dos Documentos.
Esta inscrição na Temporada de documentos é acompanhada por um rascunho de PR que abri no projeto para demonstrar algumas melhorias que proponho: https://github.com/scummvm/scummvm/pull/2361 Consulte a descrição para saber mais detalhes sobre o que ele contém e para conferir a diferença.
Confira o que o RP envolve:
1) Acho que o que mais confunde os possíveis novos colaboradores e, de modo geral, todos que acessam o documento de API atual é a falta de estrutura. A introdução da documentação estruturada da API melhoraria a legibilidade, a facilidade de localização e, consequentemente, a usabilidade do conjunto de documentos. É por isso que minha PR introduz grupos doxygen em todos os arquivos de cabeçalho na pasta "common". Com essa nova estrutura, se alguém quiser encontrar documentos sobre a API relacionada ao SO (por exemplo), eles poderão encontrar facilmente na navegação.
2) Um novo arquivo de configuração do Doxygen é configurado para permitir a criação desta documentação.
3) Um arquivo "links.doxyfile" em que todos os links usados no conjunto de documentos podem ter uma única origem. Um mecanismo útil para trabalhar com doxigênio.
4) Um CSS de doxigênio modificado. Isso é extraído de outro projeto de código aberto e é apenas um ponto de partida. O ideal é que a aparência da página do doxygen seja mais ou menos consistente com a página da Web do ScummVM.
O RP não cobre, mas definitivamente precisa ser trabalhado, é o conteúdo em si. Isso significa identificar as partes essenciais do código que não estão documentadas, as que não estão documentadas o suficiente ou as partes desatualizadas do código que precisam ser removidas da documentação. Como eu não trabalhei no projeto antes, preciso da orientação de um mentor para conseguir isso.
Obviamente, a implementação de alguma coisa da RP depende da discussão com a organização. Minha ideia era que ações valiam mais do que palavras, então decidi mostrar o que posso fazer em vez de apenas descrevê-las no aplicativo.
A organização forneceu o cronograma aproximado a seguir para este projeto: Semana Tarefa principal Semana 0 (antes de 9/14) Discussão e revisão da proposta Semana 1 (9/14) Configuração do build do Doxygen Semana 2 (9/21) Refrescamento do skin do Doxygen (baixa prioridade) Semana 3 (9/28) Código comum: OSystem, FS, estruturas de dados, strings etc. Semana 4 (10/05) Código comum: continuação Semana 5 (10/12) Engines: código comum e exemplo de engine Semana 6 (10/19) Gráficos Semana 7 (10/26) Áudio Semana 8 (11/02) Vídeo, imagens Semana 9 (11/09) Backends: plataformas, gráficos, eventos Semana 10 (11/23) Backends: continuação Semana 11 (11/30) Resumo e envio do projeto
A única mudança que eu proporia é começar trabalhando na estrutura, como já mencionado. Isso pode ser feito nas semanas 1 e 2, junto com a configuração de construção de doxigênio (que já foi feito, em grande parte) e a atualização da pele de Doxygen. Depois disso, concordo que faz mais sentido passar pelas diferentes áreas, uma a uma, com o mentor para identificar problemas e melhorar a documentação de doxigênio.
Considero este um projeto de duração padrão, mas tenho certeza de que há outras melhorias relacionadas à documentação da API que podem ser feitas após o término do projeto GSoD. Por exemplo, criar um guia de estilo de documentação e adicioná-lo à wiki para que os colaboradores saibam como documentar o código que estão adicionando.
Será um prazer ajudar com tarefas como essa depois que o GSoD terminar. Tenho certeza de que o ScummVM poderia usar um redator técnico que garantiria que a documentação da API fosse de boa qualidade e usabilidade. Também notei que há outros projetos de documentos futuros nos quais posso ajudar você, como a criação de um guia sobre como trabalhar com plug-ins.