Opensource.Platon.SK CVS: doc/soft-doc-sys/sgml/sk/developer-doc-systems.sgml - diff

   Up to  [Platon] / doc / soft-doc-sys / sgml / sk
Diff for doc/soft-doc-sys/sgml/sk/developer-doc-systems.sgml between version 1.2 and 1.3


version 1.2, 2002/12/09 22:08:03
version 1.3, 2002/12/11 18:17:42



Line 1 




Line 1 




 
 <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->


 
 


 <chapter id="developer-doc-sys"><title>Systémy vývojárskej dokumentácie softvéru</title>
 <chapter id="developer-doc-sys"><title>Systémy vývojárskej dokumentácie softvéru</title>


 
 


 <para>
 <para>


 
 


 Pre generovanie vyvojarskej dokuemtnacie existuje viacero nastrojov v zavislosti
 Pre generovanie vývojárskej dokumentácie existuje viacero nástrojov v závislosti


 na tom, v akom progrmaocom jazyku je aplikacia napisana.
 na tom, v akom programovacom jazyku je aplikácia napísaná. Pre <acronym>C/C++</>


 
 je to <ulink url="http://www.doxygen.org/"><productname>Doxygen</></>, ktorý sa


 
 vyvinul z <ulink url="http://www.doc++.org/"><productname>Doc++</></>. Pre


 
 programovací jazyk <acronym>PHP</> poznáme hneď niekoľko nástrojov: <ulink


 
 url="http://www.phpdoc.de/"><productname>phpDoc</></>, <productname>phpDoc2</>,


 
 <ulink url="http://www.phpdocumentator.org/"><productname>phpDocumentator</></>


 
 a <ulink url="http://www.peardoc.org/"><productname>PearDoc</></>. Posledný z


 
 menovaných má pred sebou zrejme najlepšiu budúcnosť, nakoľko je aktívne vyvíjaný


 
 a zrejme sa stane hlavným dokumentačným nástrojom pre <acronym>PHP</>. Nakoniec


 
 pre programovací jazyk <acronym>Java</> je to známy <ulink


 
 url="http://www.javadoc.org/"><productname>JavaDoc</></>.


 
 


 
 </para>


 
 <para>


 
 


 
 Vývojárska dokumentácia sa píše priamo do zdrojových kódov programu v podobe


 
 špeciálnych komentárov. Dokumentujú sa všetky entity programovacieho jazyka:


 
 triedy a ich metódy i atribúty, globálne a lokálne funkcie i premenné,


 
 konštanty, dátové typy ako sú napr. štruktúry, výčtové typy a iné. Dokumentačný


 
 systém pomocou špeciálnych značiek rozpozná typ informácie a na základe toho ju


 
 zakomponuje do výslednej dokumentácie.


 
 


 
 </para>


 
 <para>


 
 


 
 Nespornými výhodami uvedeného prístupu sú najmä  ušetrný čas a komplexnosť.


 
 Vďaka tomu, že sa dokumentácia píše priamo do zdrojovýh súborov, nie je nutné


 
 pracovať so zdrojovým kódom a dokumentačným súborom súčasne.  Ako už bolo


 
 spomenuté, vývojársku dokumentáciu je vhodné písať priamo počas vývoja


 
 aplikácie. A tak napríklad po pridaní novej metódy sa k nej zároveň napíše aj


 
 jednoduchý komentár, ktorý je jednak použiteľný pre informovanie o funkčnosti


 
 metódy priamo v zdrojovom kóde a samozrejme bude tiež použitý na vygenerovanie


 
 vývojárskej dokumentácie. Klasické komentáre je možné v zdrojovom kóde použivať


 
 aj naďalej, do dokumentácie zahrnuté nebudú.


 
 


 
 </para>


 
 <para>


 
 


 
 Treba zdôrazniť, že dokumentačné systémy sú schopné veľké množstvo poznatkov


 
 odvodiť priamo zo zdrojového kódu, keďže v sebe spravidla obsahujú analyzátory


 
 daného programovacieho jazyka. Napríklad do dokumentačného komentáru ku funkcii,


 
 metóde alebo triede nie je nutné písať jej meno, keďže to sa dá odvodiť<!-- EN:


 
 extract --> z príslušnej deklarácie. Toto je aj hlavný dôvod, prečo pre každý


 
 programovací jazyk existujú odlišné dokumentačné nástroje vývojárskej


 
 dokumentácie, napriek tomu, že ich použitie je v zásade totožné.


 
 


 
 </para>


 
 <para>


 
 


 
 Uvádzame ukážky zdokumentovania jednoduchej triedy v troch odlišných


 
 programovacích jazykoch (<acronym>C++</>, <acronym>PHP</>, <acronym>Java</>)


 
 pomocou ich dokumentačných systémov (<productname>Doxygen</>,


 
 <productname>PearDoc</>, <productname>JavaDoc</>). Zameriame sa najmä na


 
 spoločné črty, ktoré su pre všetky systémy zhodné. Začíname príkladom pre


 
 <productname>Doxygen</>.


 
 


 </para>
 </para>


 <para>
 <para>




Line 13  na tom, v akom progrmaocom jazyku je apl




Line 69  na tom, v akom progrmaocom jazyku je apl




 <!-- EN: <title>Documented <acronym>C++</> source code for <productname>Doxygen</></title> -->
 <!-- EN: <title>Documented <acronym>C++</> source code for <productname>Doxygen</></title> -->


 <programlisting><![CDATA[
 <programlisting><![CDATA[


 /**
 /**


  *  A test class. A more elaborate class description.
  * Example class


 
  *


 
  * More elaborate class description.


  */
  */


 class Test
 class Example


 {
 {


   public:
         public:


 
 


       /**
         /**


        * A constructor.
          * Example object constructor


        * A more elaborate description of the constructor.
          *


        */
          * More elaborate description of the constructor.


       Test();
          *


 
          * @param    bar    a bar constructor parameter


       /**
          * @param    foo    a foo constructor parameter


        * A destructor.
          * @return   void


        * A more elaborate description of the destructor.
          */


        */
         Example(int bar = 0, const char *foo = "foo");


      ~Test();
 


 
         /**


       /**
          * Example object destructor


        * a normal member taking two arguments and returning an integer value.
          *


        * @param a an integer argument.
          * More elaborate description of the destructor.


        * @param s a constant character pointer.
          */


        * @see Test()
         ~Example();


        * @see ~Test()
 


        * @see testMeToo()
 


        * @see publicVar()
 


        * @return The test results
 


        */
 


        int testMe(int a,const char *s);
 


 
 


       /**
 


        * a public variable.
 


        * Details.
 


        */
 


        int publicVar;
 


 };
 };


 ]]></programlisting>
 ]]></programlisting>


 </example>
 </example>




Line 56  class Test




Line 102  class Test




 <title>Zdokumentovaný <acronym>PHP</> zdrojový kód pre <productname>PearDoc</></title>
 <title>Zdokumentovaný <acronym>PHP</> zdrojový kód pre <productname>PearDoc</></title>


 <!-- EN: <title>Documented <acronym>PHP</> source code for <productname>PearDoc</></title> -->
 <!-- EN: <title>Documented <acronym>PHP</> source code for <productname>PearDoc</></title> -->


 <programlisting><![CDATA[
 <programlisting><![CDATA[


 TODO
 /**


 
  * Example class


 
  *


 
  * More elaborate class description.


 
  */


 
 class Example


 
 {


 
         /**


 
          * Example object constructor


 
          *


 
          * More elaborate description of the constructor.


 
          *


 
          * @param    int      bar   a bar constructor parameter


 
          * @param    string   foo   a foo constructor parameter


 
          * @return   boolean        true if this example is right,


 
          *                          false otherwise


 
          */


 
         function Example($bar = 0, $foo = 'foo')


 
         {


 
                 // Constructor code goes here. Note that PHP does not


 
                 // have anything like header files with declarations.


 
                 return true;


 
         }


 
 }


 ]]></programlisting>
 ]]></programlisting>


 </example>
 </example>


 
 




Line 69  TODO




Line 138  TODO




 </example>
 </example>


 
 


 </para>
 </para>


 
 <para>


 
 


 
 Z príkladov vidieť, že špeciálne komentáre začínajú sekvenciou <token>/**</>.


 
 Klasické <token>/*</> komentáre sa ignorujú.  Boli použité značky


 
 <token>@param</> pre definovanie vstupného funkčného parametru a


 
 <token>@return</> pre definovanie navratovej hodnoty z funkcie. Všimnite si, že


 
 zdrojový kód <acronym>C++</> už obsahuje informáciu o dátovom type vstupného


 
 parametra, preto sa v komentári nevyskytuje. Dokumentačný systém


 
 <productname>Doxygen</> si ju zistí sám. Naproti tomu zdrojový kód


 
 <acronym>PHP</> túto informáciu v sebe nemá, takže musí byť v dokumentačnom


 
 komentári uvedená.


 
 


 
 </para>


 
 <para>


 
 


 
 Medzi ďalšie značky používané na dokumentovanie funkcií alebo metód patria


 
 okrem <token>@param</> a <token>@return</> tiež <token>@access</> vyjadrujúci


 
 prístupnosť metódy (public, private, ...) a <token>@retval</> používajúci sa na


 
 opis návratovej hodnoty parametru funkcie definovaného referenciou (adresou).


 
 Ďalšie všestranne použiteľné značky sú:


 
 


 
 <simplelist type=horiz columns=2>


 
 <member> &nbsp; <token>@author</></><member> -- autor entity (triedy, metódy, funkcie)</>


 
 <member> &nbsp; <token>@version</></><member> -- verzia entity</>


 
 <member> &nbsp; <token>@date</></><member> -- dátum vzniku</>


 
 <member> &nbsp; <token>@see</></><member> -- odkaz na súvisiacu entity</>


 
 <member> &nbsp; <token>@todo</></><member> -- popis nedokončných vymožeností<!-- EN: features --></>


 
 </simplelist>


 
 


 
 </para>


 
 <para>


 
 


 
 <!-- Príklad použitia: -->


 
 


 
 <example>


 
 <title>Použitie ďaľších dokumentačných značiek</title>


 
 <programlisting><![CDATA[


 
 /**


 
  * Extensive Example class


 
  *


 
  * This extensive class does some extensive job.


 
  *


 
  * @author     Ondrej Jombik <nepto@pobox.sk>


 
  * @author     Ondrej Holotnak <beast@host.sk>


 
  * @version    1.0


 
  * @date       2002-12-11


 
  */


 
 class Extensive_Example


 
 {


 
         /**


 
          * Normal method doing something


 
          *


 
          * @param   some    some integer argument


 
          * @retval  thing   allocated string filled with thing


 
          * @return          test result


 
          * @author  Someone External <someone@example.com>


 
          * @see     Test()


 
          * @see     ~Test()


 
          * @todo    make this method something doing


 
          */


 
         int doSomething(int some, char **thing);


 
 };


 
 ]]></programlisting>


 
 </example>


 
 


 
 </para>


 
 <para>


 
 


 
 Podobne ako pri užívateľskej dokumentácii je aj tu možnosť vygenerovať finálnu


 
 dokumentáciu vo viacerých formátoch. Aplikácia


 
 <productname>Doxygen</productname> podporuje nasledovné výstupné formáty:


 
 <acronym>HTML</>, <application>LaTeX</>, <acronym>RTF</>, <acronym>XML</> a


 
 manuálové stránky. Všetko sa konfiguruje pomocou prehľadného konfiguračného


 
 súboru <filename>Doxyfile</>. Pokial spustíte program <command>doxygen</> s


 
 prepínačom <option>-g</>, základný<!-- EN: default --> konfiguračný súbor bude


 
 zapísaný na disk. Obsahuje veľa komentárov, takže jeho modifikácia je jednoduchá


 
 a priamočiara<!-- EN: straightforward -->. Samotná generácia dokumentácie


 
 prebieha nasledovným príkazom:


 
 


 
 <literallayout>


 
 <prompt>$ </><userinput> doxygen</userinput>


 
 </literallayout>


 
 


 
 Ostatné vymenované nástroje sa používajú obdobne. Nemusia však obsahovať podporu


 
 všetkých vymenovaných formátov. Určite však obsahujú možnosť generovania


 
 <acronym>HTML</> výstupu, ktorý sa považuje za najdôležitejší a najpoužiteľnejší.


 
 


 
 </para>


 </chapter>
 </chapter>


 
 









Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3


















Platon Group <platon@platon.org> http://platon.org/
  Up to  [Platon] / doc / soft-doc-sys / sgml / sk
-version 1.2, 2002/12/09 22:08:03
+version 1.3, 2002/12/11 18:17:42
 Line 1
 Line 1
 Line 1
+ <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
  <chapter id="developer-doc-sys"><title>Systémy vývojárskej dokumentácie softvéru</title>
  <para>
- Pre generovanie vyvojarskej dokuemtnacie existuje viacero nastrojov v zavislosti
+ Pre generovanie vývojárskej dokumentácie existuje viacero nástrojov v závislosti
- na tom, v akom progrmaocom jazyku je aplikacia napisana.
+ na tom, v akom programovacom jazyku je aplikácia napísaná. Pre <acronym>C/C++</>
+ je to <ulink url="http://www.doxygen.org/"><productname>Doxygen</></>, ktorý sa
+ vyvinul z <ulink url="http://www.doc++.org/"><productname>Doc++</></>. Pre
+ programovací jazyk <acronym>PHP</> poznáme hneď niekoľko nástrojov: <ulink
+ url="http://www.phpdoc.de/"><productname>phpDoc</></>, <productname>phpDoc2</>,
+ <ulink url="http://www.phpdocumentator.org/"><productname>phpDocumentator</></>
+ a <ulink url="http://www.peardoc.org/"><productname>PearDoc</></>. Posledný z
+ menovaných má pred sebou zrejme najlepšiu budúcnosť, nakoľko je aktívne vyvíjaný
+ a zrejme sa stane hlavným dokumentačným nástrojom pre <acronym>PHP</>. Nakoniec
+ pre programovací jazyk <acronym>Java</> je to známy <ulink
+ url="http://www.javadoc.org/"><productname>JavaDoc</></>.
+ </para>
+ <para>
+ Vývojárska dokumentácia sa píše priamo do zdrojových kódov programu v podobe
+ špeciálnych komentárov. Dokumentujú sa všetky entity programovacieho jazyka:
+ triedy a ich metódy i atribúty, globálne a lokálne funkcie i premenné,
+ konštanty, dátové typy ako sú napr. štruktúry, výčtové typy a iné. Dokumentačný
+ systém pomocou špeciálnych značiek rozpozná typ informácie a na základe toho ju
+ zakomponuje do výslednej dokumentácie.
+ </para>
+ <para>
+ Nespornými výhodami uvedeného prístupu sú najmä  ušetrný čas a komplexnosť.
+ Vďaka tomu, že sa dokumentácia píše priamo do zdrojovýh súborov, nie je nutné
+ pracovať so zdrojovým kódom a dokumentačným súborom súčasne.  Ako už bolo
+ spomenuté, vývojársku dokumentáciu je vhodné písať priamo počas vývoja
+ aplikácie. A tak napríklad po pridaní novej metódy sa k nej zároveň napíše aj
+ jednoduchý komentár, ktorý je jednak použiteľný pre informovanie o funkčnosti
+ metódy priamo v zdrojovom kóde a samozrejme bude tiež použitý na vygenerovanie
+ vývojárskej dokumentácie. Klasické komentáre je možné v zdrojovom kóde použivať
+ aj naďalej, do dokumentácie zahrnuté nebudú.
+ </para>
+ <para>
+ Treba zdôrazniť, že dokumentačné systémy sú schopné veľké množstvo poznatkov
+ odvodiť priamo zo zdrojového kódu, keďže v sebe spravidla obsahujú analyzátory
+ daného programovacieho jazyka. Napríklad do dokumentačného komentáru ku funkcii,
+ metóde alebo triede nie je nutné písať jej meno, keďže to sa dá odvodiť<!-- EN:
+ extract --> z príslušnej deklarácie. Toto je aj hlavný dôvod, prečo pre každý
+ programovací jazyk existujú odlišné dokumentačné nástroje vývojárskej
+ dokumentácie, napriek tomu, že ich použitie je v zásade totožné.
+ </para>
+ <para>
+ Uvádzame ukážky zdokumentovania jednoduchej triedy v troch odlišných
+ programovacích jazykoch (<acronym>C++</>, <acronym>PHP</>, <acronym>Java</>)
+ pomocou ich dokumentačných systémov (<productname>Doxygen</>,
+ <productname>PearDoc</>, <productname>JavaDoc</>). Zameriame sa najmä na
+ spoločné črty, ktoré su pre všetky systémy zhodné. Začíname príkladom pre
+ <productname>Doxygen</>.
  </para>
  <para>
-Line 13  na tom, v akom progrmaocom jazyku je apl
+Line 69  na tom, v akom progrmaocom jazyku je apl
 Line 13  na tom, v akom progrmaocom jazyku je apl
 Line 69  na tom, v akom progrmaocom jazyku je apl
  <!-- EN: <title>Documented <acronym>C++</> source code for <productname>Doxygen</></title> -->
  <programlisting><![CDATA[
  /**
-  *  A test class. A more elaborate class description.
+  * Example class
+  *
+  * More elaborate class description.
   */
- class Test
+ class Example
  {
-   public:
+         public:
-       /**
+         /**
-        * A constructor.
+          * Example object constructor
-        * A more elaborate description of the constructor.
+          *
-        */
+          * More elaborate description of the constructor.
-       Test();
+          *
+          * @param    bar    a bar constructor parameter
-       /**
+          * @param    foo    a foo constructor parameter
-        * A destructor.
+          * @return   void
-        * A more elaborate description of the destructor.
+          */
-        */
+         Example(int bar = 0, const char *foo = "foo");
-      ~Test();
+         /**
-       /**
+          * Example object destructor
-        * a normal member taking two arguments and returning an integer value.
+          *
-        * @param a an integer argument.
+          * More elaborate description of the destructor.
-        * @param s a constant character pointer.
+          */
-        * @see Test()
+         ~Example();
-        * @see ~Test()
-        * @see testMeToo()
-        * @see publicVar()
-        * @return The test results
-        */
-        int testMe(int a,const char *s);
-       /**
-        * a public variable.
-        * Details.
-        */
-        int publicVar;
  };
  ]]></programlisting>
  </example>
-Line 56  class Test
+Line 102  class Test
 Line 56  class Test
 Line 102  class Test
  <title>Zdokumentovaný <acronym>PHP</> zdrojový kód pre <productname>PearDoc</></title>
  <!-- EN: <title>Documented <acronym>PHP</> source code for <productname>PearDoc</></title> -->
  <programlisting><![CDATA[
- TODO
+ /**
+  * Example class
+  *
+  * More elaborate class description.
+  */
+ class Example
+ {
+         /**
+          * Example object constructor
+          *
+          * More elaborate description of the constructor.
+          *
+          * @param    int      bar   a bar constructor parameter
+          * @param    string   foo   a foo constructor parameter
+          * @return   boolean        true if this example is right,
+          *                          false otherwise
+          */
+         function Example($bar = 0, $foo = 'foo')
+         {
+                 // Constructor code goes here. Note that PHP does not
+                 // have anything like header files with declarations.
+                 return true;
+         }
+ }
  ]]></programlisting>
  </example>
-Line 69  TODO
+Line 138  TODO
 Line 69  TODO
 Line 138  TODO
  </example>
  </para>
+ <para>
+ Z príkladov vidieť, že špeciálne komentáre začínajú sekvenciou <token>/**</>.
+ Klasické <token>/*</> komentáre sa ignorujú.  Boli použité značky
+ <token>@param</> pre definovanie vstupného funkčného parametru a
+ <token>@return</> pre definovanie navratovej hodnoty z funkcie. Všimnite si, že
+ zdrojový kód <acronym>C++</> už obsahuje informáciu o dátovom type vstupného
+ parametra, preto sa v komentári nevyskytuje. Dokumentačný systém
+ <productname>Doxygen</> si ju zistí sám. Naproti tomu zdrojový kód
+ <acronym>PHP</> túto informáciu v sebe nemá, takže musí byť v dokumentačnom
+ komentári uvedená.
+ </para>
+ <para>
+ Medzi ďalšie značky používané na dokumentovanie funkcií alebo metód patria
+ okrem <token>@param</> a <token>@return</> tiež <token>@access</> vyjadrujúci
+ prístupnosť metódy (public, private, ...) a <token>@retval</> používajúci sa na
+ opis návratovej hodnoty parametru funkcie definovaného referenciou (adresou).
+ Ďalšie všestranne použiteľné značky sú:
+ <simplelist type=horiz columns=2>
+ <member> &nbsp; <token>@author</></><member> -- autor entity (triedy, metódy, funkcie)</>
+ <member> &nbsp; <token>@version</></><member> -- verzia entity</>
+ <member> &nbsp; <token>@date</></><member> -- dátum vzniku</>
+ <member> &nbsp; <token>@see</></><member> -- odkaz na súvisiacu entity</>
+ <member> &nbsp; <token>@todo</></><member> -- popis nedokončných vymožeností<!-- EN: features --></>
+ </simplelist>
+ </para>
+ <para>
+ <!-- Príklad použitia: -->
+ <example>
+ <title>Použitie ďaľších dokumentačných značiek</title>
+ <programlisting><![CDATA[
+ /**
+  * Extensive Example class
+  *
+  * This extensive class does some extensive job.
+  *
+  * @author     Ondrej Jombik <nepto@pobox.sk>
+  * @author     Ondrej Holotnak <beast@host.sk>
+  * @version    1.0
+  * @date       2002-12-11
+  */
+ class Extensive_Example
+ {
+         /**
+          * Normal method doing something
+          *
+          * @param   some    some integer argument
+          * @retval  thing   allocated string filled with thing
+          * @return          test result
+          * @author  Someone External <someone@example.com>
+          * @see     Test()
+          * @see     ~Test()
+          * @todo    make this method something doing
+          */
+         int doSomething(int some, char **thing);
+ };
+ ]]></programlisting>
+ </example>
+ </para>
+ <para>
+ Podobne ako pri užívateľskej dokumentácii je aj tu možnosť vygenerovať finálnu
+ dokumentáciu vo viacerých formátoch. Aplikácia
+ <productname>Doxygen</productname> podporuje nasledovné výstupné formáty:
+ <acronym>HTML</>, <application>LaTeX</>, <acronym>RTF</>, <acronym>XML</> a
+ manuálové stránky. Všetko sa konfiguruje pomocou prehľadného konfiguračného
+ súboru <filename>Doxyfile</>. Pokial spustíte program <command>doxygen</> s
+ prepínačom <option>-g</>, základný<!-- EN: default --> konfiguračný súbor bude
+ zapísaný na disk. Obsahuje veľa komentárov, takže jeho modifikácia je jednoduchá
+ a priamočiara<!-- EN: straightforward -->. Samotná generácia dokumentácie
+ prebieha nasledovným príkazom:
+ <literallayout>
+ <prompt>$ </><userinput> doxygen</userinput>
+ </literallayout>
+ Ostatné vymenované nástroje sa používajú obdobne. Nemusia však obsahovať podporu
+ všetkých vymenovaných formátov. Určite však obsahujú možnosť generovania
+ <acronym>HTML</> výstupu, ktorý sa považuje za najdôležitejší a najpoužiteľnejší.
+ </para>
  </chapter>
 Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3
 Legend:


Removed from v.1.2
 


changed lines


 
Added in v.1.3
-Removed from v.1.2
+Added in v.1.3


Copyright © 2002-2006 Platon Group Site powered by Metafox CMS	Go to Top