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

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


version 1.2, 2002/12/11 18:16:12
version 1.3, 2002/12/16 18:02:22



Line 1 




Line 1 




 <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
 <!-- $Platon: Platon.SK/doc-projects/soft-doc-sys/en/developer-doc-systems.sgml,v 1.2 2002/12/11 18:16:12 nepto Exp $ -->


 
 


 <chapter id="developer-doc-sys"><title>Developer-oriented software documentation systems</title>
 <chapter id="developer-doc-sys">


 
 <title>Developer-oriented software documentation systems</title>


 
 <para>


 
 


 <para>bar foo</para>
 There are many tools for generating the developer-oriented documentation


 
 according to the programming language the application is written in.  For


 
 <acronym>C/C++</> it is <ulink


 
 url="http://www.doxygen.org/"><productname>Doxygen</></>, which was evolved from


 
 <ulink url="http://docpp.sourceforge.net/"><productname>Doc++</></>.  For


 
 <acronym>PHP</> there are several documentation tools: <ulink


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


 
 url="http://www.phpdoc.org/"><productname>phpDocumentor</></>,


 
 <productname>PearDoc</> and <ulink


 
 url="http://pear.php.net/manual/"><productname>PearDoc2</></>.  The last named


 
 probably has the best future, because it is being actively developed and will


 
 probably become the main documentation tool for <acronym>PHP</>.  Finally, for


 
 <acronym>Java</> it is the well-known <ulink


 
 url="http://java.sun.com/j2se/javadoc/"><productname>JavaDoc</></>.


 
 


 
 </para>


 
 <para>


 
 


 
 The developer-oriented documentation is written straight in the source code of


 
 the program in the means of special comments.  All entities of the programming


 
 language are documented: classes and their methods and attributes, global and


 
 local functions and variables, constants, data types such as structures,


 
 enumerations and others.  Documentation system distinguishes the type of


 
 information according to special marks and places it in the resulting document


 
 accordingly.


 
 


 
 </para>


 
 <para>


 
 


 
 The main advantages of this approach are complexity and timesaving.  Thanks to


 
 the fact that the documentation is written into the source code files, it is not


 
 necessary to work with both source code files and documentation file


 
 simultaneously.  As already mentioned, it is appropriate to write the


 
 developer-oriented documentation when working on the code of the application.


 
 So right after adding a new method, one should write a simple comment that would


 
 be used to inform about the functionality of the method right in the source


 
 code, and will of course be used to generate the developer-oriented


 
 documentation.  It is still possible to use classical comments in the source


 
 code.  They will not be incorporated into the documentation.


 
 


 
 </para>


 
 <para>


 
 


 
 What needs to be said is that developer-oriented documentation systems are able


 
 to derive a lot of information directly from the source code, because they


 
 usually contain analyzers of the programming language.  For example, you do not


 
 need to write the name of the function, method or class in its comment, because


 
 it can be extract from its declaration.  This is the main reason why there are


 
 different developer-oriented documentation systems from every programming


 
 language, even though their use is basically the same.


 
 


 
 </para>


 
 <para>


 
 


 
 In the following examples, you can see the documentation of a simple class in


 
 three different programming languages (<acronym>C++</>, <acronym>PHP</>,


 
 <acronym>Java</>) using their documentation systems (<productname>Doxygen</>,


 
 <productname>PearDoc</>, <productname>JavaDoc</>). The emphasis is put on the


 
 features that are the same for all of these systems. Let us start with the


 
 example for <productname>Doxygen</>.


 
 


 
 </para>


 
 <para>


 
 


 
 <example>


 
 <title>Documented <acronym>C++</> source code for <productname>Doxygen</></title>


 
 <programlisting><![CDATA[


 
 /**


 
  * Example class


 
  *


 
  * More elaborate class description.


 
  */


 
 class Example


 
 {


 
         public:


 
 


 
         /**


 
          * Example object constructor


 
          *


 
          * More elaborate description of the constructor.


 
          *


 
          * @param    bar    a bar constructor parameter


 
          * @param    foo    a foo constructor parameter


 
          * @return   void


 
          */


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


 
 


 
         /**


 
          * Example object destructor


 
          *


 
          * More elaborate description of the destructor.


 
          */


 
         ~Example();


 
 };


 
 ]]></programlisting>


 
 </example>


 
 


 
 <example>


 
 <title>Documented <acronym>PHP</> source code for <productname>PearDoc</></title>


 
 <programlisting><![CDATA[


 
 /**


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


 
 


 
 <example>


 
 <title>Documented <acronym>Java</> source code for <productname>JavaDoc</></title>


 
 <programlisting><![CDATA[


 
 /**


 
  * Example class


 
  *


 
  * More elaborate class description.


 
  */


 
 class Example


 
 {


 
         /**


 
          * Example object constructor


 
          *


 
          * More elaborate description of the constructor.


 
          *


 
          * @param    bar    a bar constructor parameter


 
          * @param    foo    a foo constructor parameter


 
          * @return   void


 
          */


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


 
         {


 
                 // Constructor code goes here


 
         }


 
 }


 
 ]]></programlisting>


 
 </example>


 
 


 
 </para>


 
 <para>


 
 


 
 


 
 It can be seen from the examples that the special comments begin with the


 
 sequence <token>/**</>.  Classical <token>/*</> comments are ignored.


 
 <token>@param</> marks were used to define the input function parameter and


 
 <token>@return</> to define the return value of the function.  The source code


 
 of <acronym>C++</> already includes the information about the data type of the


 
 input parameter, therefore it is not included in the comment.


 
 <productname>Doxygen</> can find out the information by itself.  On the other


 
 hand, the <acronym>PHP</> source code does not include this information,


 
 therefore it needs to be included in the documentation comment.


 
 


 
 </para>


 
 <para>


 
 


 
 Some of the other marks used for documenting functions or methods include (apart


 
 from <token>@param</> and <token>@return</>) <token>@access</> representing the


 
 accessibility of the method (public, private, ...) and <token>@retval</> used


 
 for the description of return value to parameter of the function defined by


 
 reference (address). Other universally usable marks are:


 
 


 
 <simplelist type=horiz columns=2>


 
 <member> &nbsp; <token>@author</></><member> -- author of the entity (class, method, function)</>


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


 
 <member> &nbsp; <token>@date</></><member> -- date of creation</>


 
 <member> &nbsp; <token>@since</></><member> -- minimum version having


 
 functionality (TODO)</>


 
 <member> &nbsp; <token>@deprecated</></><member> -- TODO</>


 
 <member> &nbsp; <token>@see</></><member> -- reference to the corresponding entities</>


 
 <member> &nbsp; <token>@todo</></><member> -- list of unfinished features</>


 
 </simplelist>


 
 


 
 </para>


 
 <para>


 
 


 
 <example>


 
 <title>Use of other documentation marks</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>


 
 


 
 Similarly to the user-oriented documentation, there is the opportunity to


 
 generate the final documentation in several formats.  The


 
 <productname>Doxygen</> application supports the following formats:


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


 
 manual pages.  It is all configured using a well-defined configuration file


 
 <filename>Doxyfile</>.  If you run the <command>doxygen</> program with


 
 <option>-g</> switch, the default configuration file will be written to disk.


 
 It includes a lot of comments, so it.s modification is simple and


 
 straightforward.  The final document can be generated with the following


 
 command:


 
 


 
 <literallayout>


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


 
 </literallayout>


 
 


 
 All of the tools mentioned can be used in the same way.  They do not have to


 
 support all of the file formats though.  They all do include the opportunity to


 
 generate <acronym>HTML</> output file, which is the most important and most


 
 widely used one.


 
 


 
 </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 / en
-version 1.2, 2002/12/11 18:16:12
+version 1.3, 2002/12/16 18:02:22
 Line 1
 Line 1
 Line 1
- <!-- $Platon: phpWebFileManager/doc/sgml/changelog.sgml,v 1.3 2002/12/03 20:47:37 nepto Exp $ -->
+ <!-- $Platon: Platon.SK/doc-projects/soft-doc-sys/en/developer-doc-systems.sgml,v 1.2 2002/12/11 18:16:12 nepto Exp $ -->
- <chapter id="developer-doc-sys"><title>Developer-oriented software documentation systems</title>
+ <chapter id="developer-doc-sys">
+ <title>Developer-oriented software documentation systems</title>
+ <para>
- <para>bar foo</para>
+ There are many tools for generating the developer-oriented documentation
+ according to the programming language the application is written in.  For
+ <acronym>C/C++</> it is <ulink
+ url="http://www.doxygen.org/"><productname>Doxygen</></>, which was evolved from
+ <ulink url="http://docpp.sourceforge.net/"><productname>Doc++</></>.  For
+ <acronym>PHP</> there are several documentation tools: <ulink
+ url="http://www.phpdoc.de/"><productname>phpDoc</></>, <ulink
+ url="http://www.phpdoc.org/"><productname>phpDocumentor</></>,
+ <productname>PearDoc</> and <ulink
+ url="http://pear.php.net/manual/"><productname>PearDoc2</></>.  The last named
+ probably has the best future, because it is being actively developed and will
+ probably become the main documentation tool for <acronym>PHP</>.  Finally, for
+ <acronym>Java</> it is the well-known <ulink
+ url="http://java.sun.com/j2se/javadoc/"><productname>JavaDoc</></>.
+ </para>
+ <para>
+ The developer-oriented documentation is written straight in the source code of
+ the program in the means of special comments.  All entities of the programming
+ language are documented: classes and their methods and attributes, global and
+ local functions and variables, constants, data types such as structures,
+ enumerations and others.  Documentation system distinguishes the type of
+ information according to special marks and places it in the resulting document
+ accordingly.
+ </para>
+ <para>
+ The main advantages of this approach are complexity and timesaving.  Thanks to
+ the fact that the documentation is written into the source code files, it is not
+ necessary to work with both source code files and documentation file
+ simultaneously.  As already mentioned, it is appropriate to write the
+ developer-oriented documentation when working on the code of the application.
+ So right after adding a new method, one should write a simple comment that would
+ be used to inform about the functionality of the method right in the source
+ code, and will of course be used to generate the developer-oriented
+ documentation.  It is still possible to use classical comments in the source
+ code.  They will not be incorporated into the documentation.
+ </para>
+ <para>
+ What needs to be said is that developer-oriented documentation systems are able
+ to derive a lot of information directly from the source code, because they
+ usually contain analyzers of the programming language.  For example, you do not
+ need to write the name of the function, method or class in its comment, because
+ it can be extract from its declaration.  This is the main reason why there are
+ different developer-oriented documentation systems from every programming
+ language, even though their use is basically the same.
+ </para>
+ <para>
+ In the following examples, you can see the documentation of a simple class in
+ three different programming languages (<acronym>C++</>, <acronym>PHP</>,
+ <acronym>Java</>) using their documentation systems (<productname>Doxygen</>,
+ <productname>PearDoc</>, <productname>JavaDoc</>). The emphasis is put on the
+ features that are the same for all of these systems. Let us start with the
+ example for <productname>Doxygen</>.
+ </para>
+ <para>
+ <example>
+ <title>Documented <acronym>C++</> source code for <productname>Doxygen</></title>
+ <programlisting><![CDATA[
+ /**
+  * Example class
+  *
+  * More elaborate class description.
+  */
+ class Example
+ {
+         public:
+         /**
+          * Example object constructor
+          *
+          * More elaborate description of the constructor.
+          *
+          * @param    bar    a bar constructor parameter
+          * @param    foo    a foo constructor parameter
+          * @return   void
+          */
+         Example(int bar = 0, const char *foo = "foo");
+         /**
+          * Example object destructor
+          *
+          * More elaborate description of the destructor.
+          */
+         ~Example();
+ };
+ ]]></programlisting>
+ </example>
+ <example>
+ <title>Documented <acronym>PHP</> source code for <productname>PearDoc</></title>
+ <programlisting><![CDATA[
+ /**
+  * 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>
+ <example>
+ <title>Documented <acronym>Java</> source code for <productname>JavaDoc</></title>
+ <programlisting><![CDATA[
+ /**
+  * Example class
+  *
+  * More elaborate class description.
+  */
+ class Example
+ {
+         /**
+          * Example object constructor
+          *
+          * More elaborate description of the constructor.
+          *
+          * @param    bar    a bar constructor parameter
+          * @param    foo    a foo constructor parameter
+          * @return   void
+          */
+         Example(int bar = 0, const char *foo = "foo")
+         {
+                 // Constructor code goes here
+         }
+ }
+ ]]></programlisting>
+ </example>
+ </para>
+ <para>
+ It can be seen from the examples that the special comments begin with the
+ sequence <token>/**</>.  Classical <token>/*</> comments are ignored.
+ <token>@param</> marks were used to define the input function parameter and
+ <token>@return</> to define the return value of the function.  The source code
+ of <acronym>C++</> already includes the information about the data type of the
+ input parameter, therefore it is not included in the comment.
+ <productname>Doxygen</> can find out the information by itself.  On the other
+ hand, the <acronym>PHP</> source code does not include this information,
+ therefore it needs to be included in the documentation comment.
+ </para>
+ <para>
+ Some of the other marks used for documenting functions or methods include (apart
+ from <token>@param</> and <token>@return</>) <token>@access</> representing the
+ accessibility of the method (public, private, ...) and <token>@retval</> used
+ for the description of return value to parameter of the function defined by
+ reference (address). Other universally usable marks are:
+ <simplelist type=horiz columns=2>
+ <member> &nbsp; <token>@author</></><member> -- author of the entity (class, method, function)</>
+ <member> &nbsp; <token>@version</></><member> -- version of the entity</>
+ <member> &nbsp; <token>@date</></><member> -- date of creation</>
+ <member> &nbsp; <token>@since</></><member> -- minimum version having
+ functionality (TODO)</>
+ <member> &nbsp; <token>@deprecated</></><member> -- TODO</>
+ <member> &nbsp; <token>@see</></><member> -- reference to the corresponding entities</>
+ <member> &nbsp; <token>@todo</></><member> -- list of unfinished features</>
+ </simplelist>
+ </para>
+ <para>
+ <example>
+ <title>Use of other documentation marks</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>
+ Similarly to the user-oriented documentation, there is the opportunity to
+ generate the final documentation in several formats.  The
+ <productname>Doxygen</> application supports the following formats:
+ <acronym>HTML</>, <application>LaTeX</>, <acronym>RTF</>, <acronym>XML</> and
+ manual pages.  It is all configured using a well-defined configuration file
+ <filename>Doxyfile</>.  If you run the <command>doxygen</> program with
+ <option>-g</> switch, the default configuration file will be written to disk.
+ It includes a lot of comments, so it.s modification is simple and
+ straightforward.  The final document can be generated with the following
+ command:
+ <literallayout>
+ <prompt>$ </><userinput> doxygen</userinput>
+ </literallayout>
+ All of the tools mentioned can be used in the same way.  They do not have to
+ support all of the file formats though.  They all do include the opportunity to
+ generate <acronym>HTML</> output file, which is the most important and most
+ widely used one.
+ </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