Como escrever comentários de documentação em ANSI C?[fechado]

Question

Não consigo descobrir como escrever comentários em C. Quer dizer, sei sobre // e /* */. O que quero dizer é onde posso encontrar boas práticas?Por exemplo, se eu tiver uma função, como escrevo o @param variable is the value bla bla, como é feito em Java?

Existem padrões para isso?Ou posso apenas fazer como faço em Java?

Answer 1

Existem muitos padrões diferentes, se você deseja gerar documentação, tente doxygen

Answer 2

Não há padrões que sigam o padrão estabelecido por sua empresa.
Uma maneira popular de criar documentação de projetos é usar doxygen .

Answer 3

Você pode usar o padrão javadoc e, em seguida, usar doxygen que entende javadoc para gerar uma documentação.

No doxygen, eu recomendo usar a opção JAVADOC_AUTOBRIEF definida como YES.Se a tag JAVADOC_AUTOBRIEF for definida como YES, o doxygen interpretará a primeira linha (até o primeiro ponto) de um comentário no estilo Javadoc como uma breve descrição.

Exemplo de definição de classe:

/**
 * A brief description. A more elaborate class description
 * @param bool somebool a boolean argument.
 * @see Test()
 * @return The test results
 */

(Mais alguns exemplos no manual doxygen )

A instalação é muito simples, há uma GUI e uma bela visualização gráfica disponível com:

apt-get install doxygen doxygen-gui graphviz

Execute o gui chamando doxywizard e use as configurações do Assistente, apenas JAVADOC_AUTOBRIEF deve ser definido nas configurações "Expert".

Answer 4

Uma opção é usar o formato doxygen para escrever comentários - isso tem o benefício adicional de ser capaz de gerar html / latex e outros tipos de documentos para o seu código.