Doxygen

[neon_prannock]

Queria apresentar aos que não conhecem o Doxygen, um programa que permite documentar automaticamente o código do programa que desejarem. Para além de organizar todas os ficheiros, classes e variáveis, também "pega" nos nossos comentários e inclui-os na documentação. Também possui algumas palavras chaves que permitem separar entre descrições breves e completas, tópicos a ver também, etc... Para além de C++, também suporta outras linguagens como C, Java, Objective-C, Python, e algumas partes de PHP.

Não é muito complicado de instalar e permite exportar a documentação em HTML, entre outros formatos.

O site oficial: http://doxygen.org

[slbs@work]

Queria apresentar aos que não conhecem o Doxygen, um programa que permite documentar automaticamente o código do programa que desejarem. Para além de organizar todas os ficheiros, classes e variáveis, também "pega" nos nossos comentários e inclui-os na documentação. Também possui algumas palavras chaves que permitem separar entre descrições breves e completas, tópicos a ver também, etc... Para além de C++, também suporta outras linguagens como C, Java, Objective-C, Python, e algumas partes de PHP.

Não é muito complicado de instalar e permite exportar a documentação em HTML, entre outros formatos.

è excelente ... aproveito para acrescentar uma ferramenta muito boa para usar com o Doxygen .....

http://www.graphviz.org/

é um sw que permite ao Donygen gerar gráficos e diagramas de dependencias entre ficheiros e classe ...

os 2 em conjunto ... dá nota máxima ----

[neon_prannock]

Mais alguém que partilha a minha opinião. 🙂

Tenho que ver isso. Não conhecia...

[saramgsilva]

bem eu tive a ver o site..e pareceu ser fixe...para obter info do meu projecto dos polinomios, mas isso so da em linux??? nao é??  :down:

[neon_prannock]

Não, funciona também em Windows. Tem lá os installers.

[pedrotuga]

mmmm... isto parece.me o que procurava para escrever manuais em html.

é isto que se usa?

um manual tipo o manual do mysql ou do php sao desenvolvidos neste software?

[neon_prannock]

O doxygen não escreve manuais, apenas utiliza os comentários e a organização do teu código para apresentar uma documentação organizada e ordenada para o teu programa. Não deve ser isso que queres exactamente.

[Ped@ntilva]

Já ouvi falar no doxigen e acho muito interessante.

Já agora também funciona com PHP?

[motherFFH]

Em Novembro de 2003 -- o tempo passa mesmo depressa -- escrevi este pequeno texto sobre um apanhado que eu tinha feito a sistemas deste tipo que existiam na altura. Enviei isto a alguns colegas da minha empresa, mas ninguém ligou nada  ? damn bastards. Aqui fica ao vivo e sem cores.

---

Doclets

Como sabem, em java podem-se anotar comentários no código com determinadas marcas (tags).  O programa javadoc extrai-os/as e produz HTML.  Na verdade o javadoc é uma framework onde se encaixam doclets. Estes doclets recebem a informação proveniente das sources e fazem com ela o que quiserem. Normalmente escrevem-na num dado formato para ficheiros.

No site www.doclet.com existem uma série de doclets referenciadas, entre outras coisas associadas.

As que me mereceram destaque foram:

  1. pdfdoclet: produz PDFs directamente a partir das sources (internamente converte primeiro em html, penso eu). Esta doclet ainda está um pouco verde, tens uns bugzitos e as formatações do PDF deixam um pouco a desejar, mas é uma forma fácil de termos documentação razoável dos nossos projectos praticamente sem esforço (apliquei isto no contact center; o goncalvlu viu(?) os resultados)

  2. xdoclets: a partir de tags especiais, geram todo o tipo de código. Isto é útil quando existe muito código redundante que depende de um único ponto de código. Exemplos: web services, xml  bean descriptors, home interfaces, etc...  O luis pedro goncalvlu já usou isto, penso eu.

  3. ejbgen: uma versão especializada (e light) do xdoclets. Está orientada especificamente para a geração dos beans, e como tal alivia um pouco o peso dos xdoclets (700k vs 4M)

Sistemas de documentação a partir das fontes

Os jabardocs são porreiros mas só dão para java. Resolvi então avançar para produtos que abranjam outras linguagens.  Eis os produtos que analisei:

doc++

        doc++-3.4.10

        http://docpp.sourceforge.net/

        c, c++, idl, java

        outputs: html, latex

        . relativamente completo

        . util docify para colocar comentários nas sources que depois devem ser preenchidos

        . ultima actualizacao: inicio 2003

doxygen

        doxygen-1.3.5

        http://www.doxygen.org/

        C/C++, Java, IDL, C# and PHP

        outputs: html, latex, man, rtf, xml

        . bastante completo

        . faz cross reference (xref)

        . ultima actualizacao: ~nov 2003

naturaldocs

        NaturalDocs-1.15

        http://www.naturaldocs.org/

        C++, C#, Java, JavaScript, Perl, PHP, Python, PL/SQL, Visual Basic, Pascal, Assembly, Tcl, Ada, Text, Files

        outputs: html

        . não exige tags especiais de formação (tenta interpretar texto solto)

        . suporte a muitas linguagens

        . ultima actualizacao: ~nov 2003

doc-o-matic ($$)

        [não avaliei este]

        . pareceu muito completo

headerbrowser:

        headerbrowser-0.8.3

        http://www.headerbrowser.org

        c, c++

        outputs: html, texinfo, man

        . ultima actualizacao: 2001?

kdoc:

        version 2.0a53

        http://www.ph.unimelb.edu.au/~ssk/kde/kdoc/kdoc-snapshot.tar.gz

        c, c++, python

        outputs: html, latex, man, texinfo, docbook

        . ultima actualizacao: ~inicio 2002?

        . em perl

        . relativamente compacto

        . usado no projecto kde (ainda?)

cdoc:

        ZehDok-1.1

        http://www.khm.de/~rudi/ZehDok/ZehDok-1.0.1.tar.gz

        c (only)

        outputs: man, tex, html

        . ultima actualizacao: ~inicio 2002

        . muito compacto (8k linhas c, 2k linhas lex)

        . muito rapido e efectivo

        . relativamente limitado

scandoc:

        scandoc-0.14

        http://scandoc.sourceforge.net/

        c, c++

        outputs: html

        . ultima actualizacao: ~abril 2001

        . apenas um ficheiro de perl

De todos estes, sinceramente, penso que apenas o doc-o-matic e o doxygen valem a pena considerar. O doc-o-matic, pelas descrições, pareceu-me muito bom, mas não experimentei. É software comercial (todas as outras sao opensource), apesar de estarem disponíveis versões free-trial.  O doxygen é um autêntico balão de oxigénio (não estavam à espera que eu deixasse passar este trocadilho fácil, ein?)  que tem os seguintes destaques: suporta um conjunto apreciável de linguagens, entre as quais c, java e c# que em principio vão dominar a maior parte dos nossos projectos; tem estado a ser desenvolvido activamente (saiu uma nova versão recentemente); produz output em vários formatos: o já clássico html, latex (através deste: PS, PDF), man pages, rtf (para importar no word).

Tem ainda uma outra característica útil na manutenção de aplicações, que é cross-reference-browser.  É uma variante do output html que gera html pages de todos os ficheiros fonte convenientemente referenciados. I.e. ao ver o ficheiro x.c as variáveis são links (HREFs) para os ficheiros que as definem, tal como as funções etc... Isto é muito útil para aplicar em código que não é nosso e onde é suposto fazer qualquer coisa.

[slbs@work]

Já ouvi falar no doxigen e acho muito interessante.

Já agora também funciona com PHP?

sim, podes verificar em -> http://www.stack.nl/~dimitri/doxygen/features.html

até podes ver o potencial desta ferramenta se vires este projecto em PHP --> http://phplibex.sourceforge.net/

[Gurzi]

não percebi muito bem para que serve, alguem pode explicar melhor ?

[turiacus]

não percebi muito bem para que serve, alguem pode explicar melhor ?

  O principal objectivo desta ferramenta é criar documentação do codigo de uma forma

rápida e fácil ....  o tipo de ficheiro que gera à saida para mim é o menos importante !!!

  É essencial documentar bem o código fonte dos projectos que realizamos, especialmente 

quando é suposto alguem continuar o nosso projecto .. ou optimizar partes do nosso

projecto !! Também é bom  usar sempre a mesma norma na escrita do código [ style code]

( http://www.chris-lott.org/resources/cstyle/indhill-cstyle.html ), pois isto facilita a

compreensão do cógido. O que acabei de dizer pode ser facilmente verificado em

todos os projectos de kernel linux por exemplo... além da documentação têm um standard

de escrita do código ( nome das variavel , funçoes , livrarias, estruturas .. etc etc 

  O que este software faz internamente é organizar as funções, variaveis e livrarias 

de modo a facilitar a compeensão do código fonte ... O Graphitz ajuda o Doxygen na

medida em que introduz  diagramas de dependencia .. ie .. se um fich.h tem um

include"xpto.h" o graphitz vai desenhar um rectangulo para cado um dos ficheiros e

liga-os para uma seta ... que facilita quem vê o código pela primeira vez !!!

  Fazer isto à mão leva algum tempo ... e não fica tão bom .... e se tivermos em conta

que estas ferramentas são todas 100% freeware... ainda melhor é a solução !!! 😁😁