Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- ScummVM
- Redator técnico:
- b-gent
- Nome do projeto:
- Melhorar a documentação do código-fonte com Doxygen
- Duração do projeto:
- Duração padrão (3 meses)
Project description
A documentação atual da API ScummVM (código-fonte) está publicada aqui: https://doxygen.scummvm.org/modules.html
Infelizmente, faltam muitas áreas:
1) Praticamente nenhuma estrutura, todas as informações estão flutuando no mesmo nível.
2) Elementos C++ estão documentados de forma inconsistente com alguns deles não documentados de nenhuma forma. Isso é algo que a organização menciona como um dos principais problemas.
3) Conteúdos desatualizados e obsoletos ainda estão sendo exibidos na saída.
4) A linguagem e o uso da marcação doxygen devem ser mais consistentes. É necessário um conjunto de regras para isso, algo que poderia ser uma base para um futuro guia de estilo de documentação para este projeto.
5) O CSS doxygen usado nesta página pode ser melhorado e ficar mais parecido com o site da ScummVM: https://www.scummvm.org
Todos esses problemas podem ser resolvidos durante o projeto Season of Docs.
Esta inscrição para a temporada de documentos é acompanhada de um rascunho de RP que abri no projeto para demonstrar algumas possíveis melhorias que proponho: https://github.com/scummvm/scummvm/pull/2361 Consulte a descrição para alguns detalhes sobre o conteúdo e para ver as diferenças.
Isto é mais ou menos o que o RP envolve:
1) Acho que o que é mais confuso no momento para novos colaboradores em potencial, e geralmente todos que acessam o documento de API atual, é a falta de estrutura. A introdução de documentação estruturada de API melhoraria a legibilidade, a capacidade de localização e, consequentemente, a usabilidade do conjunto de documentos. É por isso que meu RP introduz os grupos doxygen a todos os arquivos de cabeçalho na pasta "common". Com essa nova estrutura, se alguém quiser encontrar documentos para uma API relacionada ao SO, por exemplo, será possível encontrá-los facilmente na navegação.
2) Um novo arquivo de configuração doxygen é definido para permitir a criação desta documentação.
3) Um arquivo 'links.doxyfile' do qual todos os links usados no conjunto de documentos podem ter origem única. Um mecanismo útil ao trabalhar com doxygen.
4) Um CSS de doxygen modificado. No momento, ele foi retirado de outro projeto de código aberto e é apenas um ponto de partida. O ideal é que a aparência da página doxygen seja mais ou menos consistente com a página da Web do ScummVM.
O que 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 de maneira suficiente ou as partes desatualizadas que devem ser removidas da documentação. Como eu nunca trabalhei no projeto, será necessária a orientação de um mentor para alcançar isso.
Obviamente, é questão de discutir com a organização se alguma coisa relacionada ao RP deve ser implementada. Minha ideia era que as ações falam mais do que palavras, então decidi mostrar o que posso fazer em vez de apenas descrevê-las no aplicativo.
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 criação de doxygen (que já está em grande parte) e a atualização da pele com Doxygen. Depois disso, concordo que faz mais sentido passar por diferentes áreas com o mentor, um a um, para identificar problemas e melhorar a documentação do doxygen.
Esse projeto tem tamanho 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 ao wiki, para que os colaboradores estejam cientes de como documentar o código que estão adicionando.
Será um prazer ajudar com tarefas como esta quando o GSoD terminar. Tenho certeza de que a ScummVM pode usar um redator técnico para garantir que o documento da API seja de boa qualidade e usabilidade. Também posso verificar que existem outros projetos de documentos futuros com os quais eu poderia ajudar, como a criação de um guia sobre como trabalhar com plug-ins.