Scribd Logo
Carregar

Bem-vindo(a) ao Scribd!

  • 76 visualizações

    Brams Doxygen

    Enviado por

    Luiz Flavio Rodrigues

    Direitos autorais:

    Attribution Non-Commercial (BY-NC)
    Baixe no formato PDF, TXT ou leia online no Scribd

    Brams Doxygen

    Enviado por

    Luiz Flavio Rodrigues
    76 visualizações5 páginas

    Título original

    brams-doxygen

    Direitos autorais

    © Attribution Non-Commercial (BY-NC)

    Formatos disponíveis

    PDF, TXT ou leia online no Scribd

    Você considera este documento útil?

    Este conteúdo é inapropriado?

    Direitos autorais:

    Attribution Non-Commercial (BY-NC)
    Baixe no formato PDF, TXT ou leia online no Scribd
    Fazer download em pdf ou txt
    76 visualizações5 páginas

    Brams Doxygen

    Enviado por

    Luiz Flavio Rodrigues

    Direitos autorais:

    Attribution Non-Commercial (BY-NC)
    Baixe no formato PDF, TXT ou leia online no Scribd
    Fazer download em pdf ou txt
    de 5

    Uso do Doxygen para documentao do Cdigo BRAMS.

    Um guia rpido

    Draft

    Luiz Flvio Rodrigues

    Ago/2011

    1. Introduo O Doxygen um pacote que transforma tags especiais de um determinado conjunto de arquivos fontes (Fortran, c, etc) em documentao automtica do cdigo. Essa documentao pode apresentar frmulas, figuras, textos, links e referncias para outros documentos. O pacote automaticamente gera uma referncia cruzada entre as funes, programas e sub-rotinas e tambm documenta as variveis e tipos (classes). O documento aqui apresentado trata de padronizao especfica a ser utilizada no desenvolvimento do modelo BRAMS e suas verses, bem como de seus aplicativos bsicos (bramspost, etc). 2. Instalao Para usar a documentao no ser necessria a instalao de nenhum pacote especial. Basta seguir as recomendaes do documento aqui apresentado. Assim que uma nova verso do modelo for colocada no SVN (commit) uma nova documentao ser gerada pelo gerente dos projetos. Essa nova documentao estar disponvel no site do BRAMS para consulta da comunidade. 3. Como usar As tags usadas so simples comentrios em Fortran (!) que contm estruturas e palavras chaves especficas. Essas devem estar dispostas no incio de cada programa, funo ou sub-rotina. 3.1. Bsico No incio de cada programa, sub-rotina ou funo devem ser colocados: 3.1.1. Uma descrio breve do cdigo. A tag para isso @brief 3.1.2. A denominao do autor e data. @author e @date 3.1.3. Uma referncia de copyright. @copyright e @link 3.1.4. As variveis devem ter sua descrio anexada aps a declarao. !< <descrio>

    3.2. Intermedirio Existem outras tags que podem ajudar na documentao. Essas tags permitem que se faa documentao mais detalhada. O que se pode fazer:

    3.2.1. Descrio detalhada da procedure. @details 3.2.2. Links para documentos na web. @link 3.2.3. Pargrafos especiais com qualquer nome. @par 3.2.4. Parmetros de entrada e/ou sada. @param 3.2.5. Descrio da(s) varivel(eis) retornada(s). @result, @return 3.2.6. Definio da verso da procedure. @version 3.2.7. Avisos especiais. @warning 3.2.8. Citaes de trabalho ou publicaes. @cite 3.2.9. Coisas a se fazer na rotina. @todo 3.2.10. Os textos podem conter itlico, negrito ou typewriter. @a, @b e @c O exemplo mostra algumas dessas tags e o resultado produzido.

    3.3. Avanados possvel colocar imagens, frmulas (equaes), listas ou arquivos de fluxograma (dot) para melhorar ainda mais a documentao. As frmulas usam o formato do Latex. Os arquivos de fluxograma (caixinhas, etc) fazem uso do GraphViz e tem sua linguagem prpria. 3.3.1. As imagens devem ser inseridas partir de um diretrio conhecido ou partir de um endereo na internet. @image 3.3.2. As frmulas podem ser inseridas embebidas no texto ou de forma especfica. \f$ \f$ ou \f[ ... \f] 3.3.3. As listas usam o mesmo conceito de listas em html. @li 3.3.4. Os arquivos de fluxograma ou diagramas. @dot @enddot

    4. Recomendaes BRAMS Abaixo algumas tags mnimas recomendadas para o uso no BRAMS. 4.1. 4.2. 4.3. 4.4. 4.5. 4.6. 4.7. @detail: Deve conter uma descrio mais profunda da procedure @brief: Para cada verso nova (correes , etc) descrever o que foi feito @author: Descrever o autor dos releases, correo de bugs, verses, etc @date: Colocar a data de cada verso. @version: Mostrar a verso da procedure. @param: Mostrar os parmetros de entrada. @return: Mostrar os parmetros de sada.

    5. Observaes teis: 5.1. Havendo possibilidade fazer a correta documentao. Apontar os links para os documentos e publicaes disponveis na internet. 5.2. Se a funo ou subrotina resolve parte de uma equao descrev-la. Caso a equao esteja diluda em partes no cdigo recomendvel que cada parte seja uma subrotina ou funo e tenha sua documentao descrita. 5.3. Nas rotinas de leitura ou escrita vale a pena fazer um diagrama simples mostrando quais arquivos so lidos e descrev-los suscintamente. 5.4. Caso o procedure no possa ser usado para alguma aplicao, tenha falhas no corrigveis para certos casos ou qualquer necessidade do tipo, colocar um warning na documentao. 5.5. Necessidades futuras (tarefas) devem ser mostradas atravs de uma tag todo para que todos possam interagir em sua criao. 5.6. Qualquer pargrafo especial na documentao pode e deve ser criado. Isso ajuda a organizar as coisas (use par). 6. Referncias 6.1. 6.2. 6.3. 6.4. 6.5. Doxygen Manual [OnLine]. http://www.stack.nl/~dimitri/doxygen/manual.html GraphViz. Graph Vizualization Software. http://www.graphviz.org/Gallery.php MathJax. OnLine Math Formulas. http://www.mathjax.org/ Latex Lessons. http://crab.rutgers.edu/~karel/latex/class4/class4.html BRAMS. http://brams.cptec.inpe.br/

    Você também pode gostar