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