Será que não existe um “wiki” para editar comentários doxygen? [fechadas]

Question

Eu estou trabalhando em um bastante grande motor open source RTS jogo ( Primavera ). I recentemente adicionou um monte de novas funções C ++ que pode ser chamado por Lua, e estou querendo saber a melhor forma de documento eles, e ao mesmo tempo também estimular as pessoas a documentação escrita / atualização para muito de call Lua existente outs.

Então, eu percebi isso pode ser bom se eu pudesse escrever a documentação inicialmente como comentários doxygen perto as funções de C ++ - este é fácil, porque o corpo da função, obviamente, define exatamente o que a função faz. No entanto, eu gostaria que a documentação a ser melhorada por desenvolvedores de jogos, utilizando o motor, que geralmente têm pouca compreensão do git (VCS usamos) ou C ++.

Por isso, seria ideal se houvesse uma maneira de gerar automaticamente apidocs do C ++ arquivo, mas também para ter um wiki-like interface web para permitir que um público muito mais amplo para atualizar os comentários, adicionar exemplos, etc.

Então, eu estou perguntando, será que existe uma ferramenta web que integra estilo doxygen formatação, wiki-like edição para esses comentários (de preferência sem permitir a edição de quaisquer outras partes do arquivo de origem) e git? (Para confirmar as observações alterados através da interface web para um ramo especial)

Nós, os desenvolvedores podem em seguida, mesclar este ramo de vez em quando para adicionar as melhorias para o branch master, e ao mesmo tempo todas as melhorias por desenvolvedores para a documentação acabaria sobre essa ferramenta web com apenas um merge do branch master neste ramo especial.

Eu não encontrei nada ainda, dúvida algo tão específico existe ainda, então todas as sugestões são bem-vindos!

Answer 1

Esta é uma idéia muito legal mesmo, e um par de anos atrás eu também tinha uma necessidade muito forte para algo como isso. Infelizmente, pelo menos naquela época, eu não era capaz de encontrar algo parecido. Fazendo uma busca rápida no SourceForge e freshmeat também não trazer qualquer coisa relacionada hoje.

Mas eu concordo que tal frontend wiki a documentação usuário contribuiu seria muito útil, eu sei para um fato que algo como isso foi recentemente sendo discutido também dentro da comunidade Lua (ver este ).

Assim, talvez possamos determinar os requisitos, a fim de chegar a um básica projecto de trabalho / protótipo?

Esperamos que este iria obter indo para iniciar tal projeto um com um conjunto mínimo de recursos e, em seguida, simplesmente liberá-lo para a vida selvagem como um projeto de código aberto (por exemplo, no SourceForge), para que outros usuários podem contribuir para isso.

manchas Idealmente, pode-se usar a Unificação para aplicar as alterações que foram contribuíram de forma tão a. Além disso, ele provavelmente faria sentido para restringir modificações apenas para adicionar / editar comentários, em vez de permitir modificações arbitrárias de texto, isso provavelmente poderia ser implementado usando uma regex simples.

Talvez, pode-se implementar algo parecido modificando um (estabelecido) software wiki existente, como MediaWiki. Ou, de preferência algo que já está usando git como um backend para fins de armazenamento. Então, pode-se, principalmente, precisa atender a esses comentários Doxygen-estilo, e fornecer uma interface simples em cima dela.

Thinking sobre isso um pouco mais, em si Doxygen já fornece suporte para documentação de geração de HTML, de modo que a partir dessa perspectiva que poderia ser realmente interessante ver, como Doxygen poderia ser estendido, de modo que ele é bem integrado com tal backend script que permite uma fácil personalização da documentação do código fonte embutido.

Este seria provavelmente principalmente resumem-se a fornecer um script autônomo com doxygen (por exemplo, em python, php ou perl) e, em seguida, formas opcionalmente incorporar na documentação HTML criado automaticamente, de modo que correções de documentação / aumentos podem ser enviadas para o script correspondente através de um navegador, que por sua vez iria escrever quaisquer modificações de volta a um ramo correspondente.

No longo prazo, seria legal se esse script a apoiaria diferentes tipos de backends (CVS, SVN ou git), ou pelo menos ser implementada genericamente o suficiente, de modo que é facilmente extensível.

Então, se nós podemos vir acima com um bom design, pode até ser possível que tal modificação de um seria geralmente aceite como uma contribuição para doxygen em si, que também daria a coisa toda muito mais exposição e momento.

Mesmo que a ideia não se materializa diretamente em um projeto real, seria interessante ver quantos outros usuários realmente gosto da idéia, de modo que poderia ser mencionado no issue tracker doxygen ( https://github.com/doxygen/doxygen/issues/new ).

EDIT: Você também pode querer verificar para fora este artigo intitulado < a href = "http://morch.com/content/documentation-git-and-mediawiki" rel = "nofollow noreferrer"> "Documentação, Git e MediaWiki" .