02-documentation/index.php

Go to the documentation of this file.
00001 <?php
00019 function display_documentation_page()
00020 {
00021     ?>
00022         <html>
00023         <head>
00024             <title>PHP documentation</title>
00025             <style type="text/css">
00026                 p {text-align:justify}
00027             </style>
00028         </head>
00029         <body>
00030             <h3>PHP documentation</h3>
00031 
00032             <p>
00033                 There are two seemingly unrelated purposes of this example.
00034                 First is to provide links to PHP documentation so that
00035                 students can refer to it while writing code. 
00036             </p>
00037 
00038             <p>
00039                 PHP being open source and collaboratively developed, is very
00040                 well documented. This is necessary for so many people to work
00041                 together. To add to this PHP documentation supports comments
00042                 where users post very useful code snippets related to function
00043                 whose documentation is being discussed. Thus documentation not
00044                 only includes description of function, but also several examples
00045                 where the function has been used to achieve good results. Thus making
00046                 PHP online documentation indepensible resource while using PHP.
00047                 If Internet connection is a problem then various downloadable versions
00048                 of documentation are also avaiable.
00049             </p>
00050 
00051             <h4>Important documentation links:</h4>
00052             <ul>
00053                 <li><a href="http://www.php.net/manual/en/" target="_blank">PHP manual english</a></li>
00054                 <li><a href="http://www.php.net/manual/en/indexes.php" target="_blank">Function index (My favorite)</a></li>
00055                 <li><a href="http://www.php.net/docs.php" target="_blank">Top level documentation page</a></li>
00056             </ul>
00057     
00058     
00059             <h3>Doxygen</h3>
00060             <p>
00061                 Other purpose of this page is to explain about doxygen and automated documentation.
00062                 There are two types of comments supported by PHP:
00063             </p>
00064             <ol>
00065                 <li>Single line comments starting with //</li>
00066                 <li>Multiple line comments enclosed in /* */</li>
00067             </ol>
00068 
00069             <p>
00070                 This is same as many other languages like C, Java etc. For purpose of documentation
00071                 a third type of comment can be used in all these languages, called documentation
00072                 comments. Documentation comments start with . Hence as far as
00073                 compilers or interpreters are concerned there is no difference between documentation
00074                 comments and multi-line comments and hence they simply ignore it. These comments are
00075                 used by tools like doxygen, javadoc etc. which generate documentation in various
00076                 formats with help of these comments.
00077             </p>
00078 
00079             <p>
00080                 Use '<tt>doxygen -g</tt>' to generate a doxygen configuration file. The file is huge
00081                 and heavily commented. Modify following parameters in configuration file with appropriate 
00082                 values:
00083             </p>
00084             <dl>
00085                 <dt>PROJECT_NAME : </dt>
00086                 <dd>
00087                     Fill in some proper project name like "PHP example documentation" (with quotes)
00088                 </dd>
00089 
00090 
00091                 <dt>PROJECT_NUMBER : </dt>
00092                 <dd>
00093                     Any number like 1.0 is fine. This would be useful if version control systems like
00094                     subversion, git, cvs, etc. are used. We will try to cover subversion in this course
00095                     later on, based on available time.
00096                 </dd>
00097 
00098 
00099                 <dt>OUTPUT_DIRECTORY : </dt>
00100                 <dd>
00101                     Keep output directory outside the top-level source code directory. Path of output
00102                     directory can be relative so that you can specify something like ../documentation
00103                     to generate documentation in another sub-folder of parent folder.
00104                 </dd>
00105 
00106 
00107                 <dt>ALWAYS_DETAILED_SEC : </dt>
00108                 <dd>
00109                     Set to YES
00110                 </dd>
00111     
00112 
00113                 <dt>FULL_PATH_NAMES : </dt>
00114                 <dd>
00115                     Set to NO
00116                 </dd>
00117 
00118                 
00119                 <dt>JAVADOC_AUTOBRIEF : </dt>
00120                 <dd>
00121                     Set to YES
00122                 </dd>
00123 
00124                 
00125                 <dt>TAB_SIZE : </dt>
00126                 <dd>
00127                     Set to 4
00128                 </dd>
00129 
00130 
00131                 <dt>EXTRACT_ALL : </dt>
00132                 <dd>
00133                     Set to YES
00134                 </dd>
00135 
00136 
00137                 <dt>EXTRACT_STATIC : </dt>
00138                 <dd>
00139                     Set to YES
00140                 </dd>
00141 
00142 
00143                 <dt>SORT_BRIEF_DOCS :</dt>
00144                 <dd>
00145                     Set to YES
00146                 </dd>
00147 
00148 
00149                 <dt>WARN_NO_PARAMDOC :</dt>
00150                 <dd>
00151                     Set to YES
00152                 </dd>
00153 
00154 
00155                 <dt>INPUT : </dt>
00156                 <dd>
00157                         Specify parent folder in which all code files are present. If Doxygen config
00158                         file is present in parent code folder then you can specify INPUT as '.', that
00159                         is current folder. When using Doxygen in this manner the OUPUT should be
00160                         something like '../documentation' so that documentation itself does not gets
00161                         processed by Doxygen.
00162 
00163                     <span style="font-weight:bold">
00164                         If you are new to Doxygen then take backup of code folder before trying to use
00165                         Doxygen until you are comfortable with it.
00166                     </span>
00167                 </dd>
00168 
00169 
00170                 <dt>FILE_PATTERNS :</dt>
00171                 <dd>
00172                     Set to *.php
00173                 </dd>
00174 
00175 
00176                 <dt>RECURSIVE : </dt>
00177                 <dd>
00178                     Set to YES
00179                 </dd>
00180                 
00181 
00182                 <dt>SOURCE_BROWSER : </dt>
00183                 <dd>
00184                     Set to YES
00185                 </dd>
00186 
00187                 
00188                 <dt>INLINE_SOURCES : </dt>
00189                 <dd>
00190                     Set to NO
00191                 </dd>
00192 
00193 
00194                 <dt>ALPHABETICAL_INDEX : </dt>
00195                 <dd>
00196                     Set to YES
00197                 </dd>
00198     
00199                 <dt>GENERATE_LATEX : </dt>
00200                 <dd>
00201                     Set to NO
00202                 </dd>
00203             </dl>
00204 
00205 
00206             <p>
00207                 After configuring doxygen running it from same folder using '<tt>doxygen</tt>' command.
00208                 Browse through generated documentation. 
00209             </p>
00210         </body>
00211         </html>
00212 
00213     <?php
00214 }
00215 
00216 
00217 display_documentation_page();
00218 
00219 
00220 ?>
00221 
00222 

Generated on Fri Nov 4 14:16:54 2011 for PHP example documentation by  doxygen 1.4.7