Jump to content

Recommended Posts

Posted

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

  • 2 months later...
Posted

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 ----

  • 2 weeks later...
  • 2 weeks later...
Posted

Em Novembro de 2003 -- o tempo passa mesmo depressa :wallbash: -- 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.

  • 4 weeks later...
  • 1 month later...
Posted

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 !!! 😁😁

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
×
×
  • Create New...

Important Information

By using this site you accept our Terms of Use and Privacy Policy. We have placed cookies on your device to help make this website better. You can adjust your cookie settings, otherwise we'll assume you're okay to continue.