Universidade Federal do Rio Grande do Norte Prtica de Algoritmos e Estrutura de Dados I Rivaldo Rodrigues

DOXYGEN
1-

Introduo

Esse tutorial tem como o !etivo a"resentar e estimular o aluno a usar uma #erramenta de documentao de c$digo% Em termo de re-usa ilidade de so#t&are a documentao se mostra de vital im"ort'ncia visto (ue uma das "rinci"ais #un)es de uma oa documentao de c$digo * a"resentar ao usurio uma viso geral dos "rogramas ou da API +A""lication Programming Inter#ace, a ser utili-ado "elo c$digo cliente sem. no entanto. e/"or detal0es da im"lementao. tornando assim mais #cil a utili-ao +re-utili-ao, do mesmo% A utili-ao de uma #erramenta de documentao automtica tem a vantagem de "ermitir (ue nos concentremos em ela orar uma oa descrio do c$digo. ao inv*s de "erdermos tem"o com detal0es relativos 1 a"ar2ncia (ue tal documentao ter "ara o usurio #inal% Isso acontece "ois. a "rinci"al #uno da #erramenta * utili-ar as marcaes geradas no c$digo #onte "ara criar e organi-ar a documentao em #ormatos "o"ulares e "u lica)es eletr3nicas como HTML ou pdf +via late/,% A"resentaremos durante este te/to a #erramenta Do/4gen (ue consiste num sistema de documentao "ara 566. 5. 7ava. 8 !ective-5. P4t0on. ID9 e algumas e/tens)es de P:P. 5; e D% <ers)es do Do/4gen "odem ser encontradas "ara =indo&s. 9inu/ e >ac 8?% <ale salientar (ue este documento uscar a"resentar a"enas os elementos sicos "ara se criar uma documentao utili-ando Do/4gen% 5aso se!a do interesse do leitor a"render a utili-ar as #un)es avanadas de documentao. recomenda-se a leitura do tutorial do desenvolvedor em 0tt"@AA&&&%stacB%nlACdimitriAdo/4genAmanual%0tml

D Instalao e con#igurao
Eai/e gratuitamente a verso do Do/4gen es"eci#ica "ara o seu sistema o"eracional no site &&&%do/4gen%org ou de algum gerenciador de de "acotes +como o ?4na"tc no 9inu/,% ?iga a "rocedimento de instalao de acordo com o seu sistema o"eracional%

Agora (ue o do/4gen esta devidamente instalado. "odemos utili-a-lo "ara criar documentao de ar(uivos% Para isso usamos o comando F do/4gen ar(uivo%0 +ou %c"", no mesmo diret$rio do ar(uivo% A"$s isso ser criado duas "astas. uma com a documentao em :G>9 e outra em 9ate/% Note "ortanto (ue o do/4gen. "or "adro. no criar a documentao (ue no se!am de classe. como. "or e/em"lo. um ar(uivo c"" contendo s$ a main+,% >ostraremos agora como con#igurar algumas o")es sicas% Alguns dos "rocedimentos "ara demonstrados "odem ter uma sinta/e di#erente de"endendo da verso utili-ada% Para con#igurar as o")es ao se gerar o c$digo deve se "rimeiramente criar um ar(uivo de con#igurao% Para isso digitamos o comando@ F do/4gen -g nomeHdoHar(uivo 5om isso. o do/4gen gerar um ar(uivo com o nome es"eci#icado contendo as o")es de con#igurao% Uma leitura do ar(uivo de con#igurao nos "ermite con0ecer in#orma)es so re o (ue cada o"o re"resenta% Algumas destas o")es so@ 8UGPUGH9ANGUAGE I Era-ilian Gera o documento em "ortugu2s+Erasil, EJGRA5GHA99 I KE? Gera a documentao de todos os elementos +incluindo #un)es #ora de uma classe, Estas e vrias outras o")es "odem ser modi#icadas% Para criar uma documentao com ase no ar(uivo de con#igurao "reviamente gerado usamos o comando@ F do/4gen ar(uivoHcon# ar(uivo%0 +ou c"",

L - Documentando o c$digo
Um loco de documentao no estilo Do/4gen di#ere ligeiramente do "adro do 566. "or e/em"lo. "or re(uerer algumas marcas adicionais% Essas marcas di#ere da sinta/e do Do/4gen "ois este consiste em algumas o res"onsveis "or "ermitir (ue o Do/4gen recon0ea (ue a(uela "arte do documento deve ser usada na 0ora de gerar a documentao%

Para cada item do c$digo 0 dois ti"os de descrio (ue !untos #ormam a documentao@ descrio breve e descrio detalhada% Am as so o"cionais "or*m. utili-ar mais de uma descrio do mesmo ti"o no * "ermitido% Uma descrio reve consiste num comentrio de Mnica lin0a. ! a descrio detal0ada. como es"erado. "ode ocu"ar diversas lin0as% 3.1 - Comentrios detalhados : vrios modos de se marcar uma descrio detal0ada@ 1% Pode ser usado o estilo do 7avaDoc . o (ual consiste em loco de comentrio estilo 5 iniciando-se com dois asteriscos +N,@
/** * ... texto ... */

D% Alternativamente. voc2 "ode usar o estilo Ot e adicionar uma e/clamao a"$s o inicio do com loco de comentrio estilo 5 como mostra o e/em"lo@
/*! * ... texto ... */

Em am os os casos os asteriscos +N, das demais lin0as. e/certo o (ue #inali-a o comentrio +NA, so o"cionais%
/*! * ... texto ... */

L% A terceira alternativa consiste em utili-ar um loco de "elo menos dois comentrios de lin0a estilo 566 acrescentando uma arra adicional ou um sinal de e/clamao%
/// /// ... texto ... /// //! //! ... texto ... //!

P% Pode se tam *m dei/a o comentrio mais visQvel como a e/em"lo de@

///////////////////////////////////////////////// /// ... texto ... /////////////////////////////////////////////////

3.

- Comentrios breves

Para se construir um comentrio reve "odemos@ 1% Usar o comando !brief em um dos locos de comentrio% Esse comando termina a"$s o #im do "argra#o. ou se!a. a"$s uma lin0a em ranco%
/*! \brief Descrio breve * continuao da descrio. * * Inicio a descrio detalhada. */

D% ?e a o"o 7A<AD85HAUG8ERIEF no ar(uivo de con#igurao estiver selecionado como "#$ "ode ser usado o estilo 7avaDoc. assim. o comentrio vai iniciar automaticamente com um comentrio reve o (ual termina a"$s o "rimeiro "onto #inal@
/** Descrio breve termina aps este ponto. Se ue ento a * descrio detalhada. */

8 temos o mesmo e#eito utili-ando o estilo 566@

/// Descrio breve termina aps este ponto. Se ue ento a /// descrio detalhada.

L% Uma terceira #orma * utili-ar o estilo 566 de comentrio de #orma a no se estender "or mais de uma lin0a% 5omo nos dois e/em"los a seguir@
/// Descrio breve. /** Descrio detalhada. */

ou
//! Descrio breve. //! Inicio da descrio //! detalhada.

Note (ue #oi utili-ado uma lin0a em ranco no ultimo e/em"lo "ara se"arar os dois ti"os de descrio% 8 c$digo seguinte no re"resenta uma descrio valida. "ois s$ * "ossQvel uma descrio reve "or #uno. classe ou varivel@

//! Descrio breve! a "ual utili#e mais //! De uma linha $ tida como uma descrio detalhada. /*! %ops! &"ui temos outra descrio detalhada! */

5aso e/ista uma descrio reve antes de uma declarao e outra a"$s a mesma. a"enas a descrio (ue "recede a declarao ser utili-ada% 8 mesmo ocorre "ara descri)es detal0adas% A(ui esta um e/em"lo de documentao no estilo Ot de uma classe em 566. mais adiante sero a"resentadas outras #erramentas "ara descrevemos com"letamente a classe teste@
//! /*! * */ 'ma classe teste. 'ma descrio mais elaborada.

class (est ) *ublic+ //! ,onstrutor. /*! 'ma descrio detalhada do construtor. */ (est-./ //! Destrutor. /*! 'ma descrio detalhada do desctrutor. */ 0(est-./ ....... 1/

A(ui esta a mesma classe documentada usando o estilo 7avaDoc e a o"o 7A<AD85HAUG8ERIEF selecionada como KE?@
/** * 'ma classe teste. 'ma descrio mais elaborada. */ class (est ) public+ /** * ,onstrutor. * 'ma descrio detalhada do construtor. */ (est-./ /**

* Destrutor * 'ma descrio detalhada do destrutor. */ 0(est-./ .. ... 1/

Note (ue em ora o construtor e o destrutor no este!am im"lementados a documentao "recede os mesmo. ou se!a. a documentao vem onde o m*todo. varivel ou classe #oi de#inido "rimeiro% 3.3 %oc&mentao ap's a declarao de membros. 5aso voc2 (ueira documentar os mem ros de dados. ar(uivos. estruturas. classes ou enumera)es voc2 ter (ue colocar a documentao antes do mesmo% No entanto. as ve-es * mais vivel escrever a documentao a"$s a declarao% Para esse "ro"$sito n$s usamos o sQm olo R "ara relacionar o comentrio% A(ui n$s temos alguns e/em"los@
int var/ /*!2 Descrio detalhada aps membro de dados */

ou@
int var/ /**2 Descrio detalhada aps membro de dados */

ou
int var/ //!2 Descrio detalhada aps membro de dados //!2

ou ainda@
int var/ ///2 Descrio detalhada aps membro de dados ///2

Geralmente usa-se a"enas uma descrio reve a"$s os mem ros como segue@
int var/ //!2 Descrio breve de membros de dados

ou
int var/ ///2 Descrio breve de membros de dados

<ale salientar (ue este novo m*todo de descrio segue as mesmas #uncionalidade dos m*todos anteriores% No e/em"lo a ai/o. temos o uso deste novos m*todos@

/*! 'ma classe teste */ class (est ) public+ /**! 'ma enumerao. * % bloco de documentao no pode ser colocado depois da * enumerao */ enum 3num(4pe ) int 35al6! /**2 5alor 6 */ int 35al7 /**2 5alor 7 */ void member-./ protected+ int value/ 1/ //!2 'ma funo membro /*!2 'm valor inteiro */

1/

(ota) Esses m*todo s$ "ode ser usado "ara documentar mem ros de dados e #un)es% Ele no "ode ser usado "ara documentar um ar(uivo. classe. unio. enumerao ou names"ace% 3.* - %oc&mentando f&nes <rios "ar'metros adicionais "odem ser acrescentados 1 documentao ! a"resentada no (ue se re#ere as #un)es% 8 (uadro a ai/o a"resenta alguma delas@
\param Indica os par8metros recebidos pela funo. \sa ,aso se "ueira fa#er referencia a outra funo 9: existente! aps a documentao ser erada teremos um lin; para as fun<es referenciadas. \return Indica o retorno da funo

A ai/o temos e/em"los de uso desses "ar'metros na documentao de #un)es%

//! 'ma funo membro para teste. /*! \param a um inteiro "ue representa o tamanho do arra4. \param s um ponteiro constante para um arra4 de char. \return um inteiro. \sa (est-.! 0(est-.! test=e(oo-. and public5ar-. */ int test=e-int a! const char *s./

ou "odemos ainda utili-ar o estilo 7avaDoc

/** * 'ma funo membro para teste. * >param um inteiro "ue representa o tamanho do arra4. * >param s um ponteiro constante para um arra4 de char. * >see (est-. * >see 0(est-. * >see test=e(oo-. * >see public5ar-. * >return um inteiro. */ int test=e-int a!const char *s./

3.+ - %ados de cabealho 8 Do/4gen "ossui alguns "ar'metros es"ecQ#icos na criao de ca eal0os em "rogramas. tais ca eal0os tem o intuito de in#ormar dados como@ o autor do ar(uivo. data da im"lementao. verso do ar(uivo. etc% A"resentaremos agora os "rinci"ais "ar'metros "ara um ca eal0o% Utili-ando um loco de comentrio como mostrado anteriormente. acrescentamos "ar'metros es"eci#ico "ara cada utilidade% ?o eles@ !a&thor Indica o autor da classe +ar(uivo, !since Indica a data da "rimeira im"lementao !version Indica a verso atual A segui temos um e/em"lo de como esses "ar'metros "odem ser colocados em "ratica utili-ando o estilo Ot%
//! /*! * * * */ Descrio do ar"uivo. \author ?ome do &utor. \since 6@/6@/6@ \version 6.@

8 estilo 7avaDoc tam *m "ode ser utili-ado. como no e/em"lo a ai/o@

/** /* * * * */ Descrio do ar"uivo. >author ?ome do &utor. >since 6@/6@/6@ >version 6.@

* - #,emplo

Por #im. a"resentaremos um e/em"lo da documentao com"leta. a (ual #oi construQda ao longo deste te/to em estilo Ot +lem rando (ue a mesma "ode ser construQda no estilo 7avaDoc,% ?ugiro ao leitor (ue co"ie +ou escreva, o c$digo a ai/o em um ar(uivo +ar(uivo%0 "or e/em"lo, e use a #erramenta Do/4gen "ara con#erir o resultado gerado%
//! /*! * * * */ 'ma classe teste. 'ma descrio mais elaborada. \author ?ome do &utor. \since 6@/6@/6@ \version 6.@

class (est ) public+ //! ,onstrutor. /*! 'ma descrio detalhada do construtor. */ (est-./ //! Destrutor. /*! 'ma descrio detalhada do desctrutor. */ 0(est-./ //! 3numerao. /*! 'ma descrio detalhada da enumerao */ enum (3num ) (5al6! /*!2 5alor (5al6. */ (5al7! /*!2 5alor (5al7. */ (5alA /*!2 5alor (5alA. */ 1 //! *onteiro para enumerao. /*! Detalhes */ *enum*tr! //! 5ari:vel para enumerao. /*! Detalhes */ enum5ar/ //! /*! * * * * 'ma funo membro para teste.

\param a um inteiro "ue representa o tamanho do arra4. \param s um ponteiro constante para um arra4 de char. \return um inteiro. \sa (est-.! 0(est-.! test=e(oo-. and public5ar-. */ int test=e-int a! const char *s./ 1/