[PHP-DOC] cvs: phpdoc /howto working.xml

[Philip Olson]

philip          Tue Sep  5 18:28:38 2006 UTC

  Modified files:              
    /phpdoc/howto       working.xml 
  Log:
  Added the notes, unicode, and errors sections to the function skeleton, 
  and a few minor edits to it as well.
  
  
http://cvs.php.net/viewvc.cgi/phpdoc/howto/working.xml?r1=1.61&r2=1.62&diff_format=u
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.61 phpdoc/howto/working.xml:1.62
--- phpdoc/howto/working.xml:1.61       Thu May 11 13:41:36 2006
+++ phpdoc/howto/working.xml    Tue Sep  5 18:28:38 2006
@@ -494,7 +494,7 @@
     <title>A function skeleton (<filename>func-name.xml</filename>)</title>
     <programlisting role="xml">
 &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
-&lt;!-- $Revision: 1.61 $ --&gt;
+&lt;!-- $Revision: 1.62 $ --&gt;
 &lt;refentry id="function.func-name"&gt;
  &lt;refnamediv&gt;
   &lt;refname&gt;func_name&lt;/refname&gt;
@@ -518,6 +518,7 @@
    The functions description goes here.
   &lt;/para&gt;
  &lt;/refsect1&gt;
+ 
  &lt;refsect1 role="parameters"&gt;
   &amp;reftitle.parameters;
   &lt;para&gt;
@@ -538,17 +539,10 @@
       &lt;/para&gt;
      &lt;/listitem&gt;
     &lt;/varlistentry&gt;
-    &lt;varlistentry&gt;
-     &lt;term&gt;&lt;parameter&gt;thirdparameter&lt;/parameter&gt;&lt;/term&gt;
-     &lt;listitem&gt;
-      &lt;para&gt;
-       Its description
-      &lt;/para&gt;
-     &lt;/listitem&gt;
-    &lt;/varlistentry&gt;
    &lt;/variablelist&gt;
   &lt;/para&gt;
  &lt;/refsect1&gt;
+ 
  &lt;refsect1 role="returnvalues"&gt;
   &amp;reftitle.returnvalues;
   &lt;para&gt;
@@ -556,6 +550,21 @@
    true on success and false on failure, just use &amp;return.success; here.
   &lt;/para&gt;
  &lt;/refsect1&gt;
+ 
+ &lt;refsect1 role="errors"&gt;
+  &amp;reftitle.errors;
+  &lt;para&gt;
+   When does this function issue E_* level errors, or throw exceptions?
+  &lt;/para&gt;
+ &lt;/refsect1&gt;
+
+ &lt;refsect1 role="unicode"&gt;
+  &amp;reftitle.unicode;
+  &lt;para&gt;
+   Unicode information (introduced in PHP 6) goes here.
+  &lt;/para&gt;
+ &lt;/refsect1&gt;
+
  &lt;refsect1 role="changelog"&gt;
   &amp;reftitle.changelog;
   &lt;para&gt;
@@ -569,7 +578,7 @@
      &lt;/thead&gt;
      &lt;tbody&gt;
       &lt;row&gt;
-       &lt;entry&gt;Write the PHP version here (Ex. 4.3.0)&lt;/entry&gt;
+       &lt;entry&gt;Write the PHP version here (Ex. PHP 5.2.0)&lt;/entry&gt;
        &lt;entry&gt;
         Describe the change
        &lt;/entry&gt;
@@ -585,6 +594,7 @@
    &lt;/informaltable&gt;
   &lt;/para&gt;
  &lt;/refsect1&gt;
+ 
  &lt;refsect1 role="examples"&gt;
   &amp;reftitle.examples;
   &lt;para&gt;
@@ -612,6 +622,16 @@
    &lt;/example&gt;
   &lt;/para&gt;
  &lt;/refsect1&gt;
+
+ &lt;refsect1 role="notes"&gt;
+  &amp;reftitle.notes;
+  &lt;para&gt;
+   Any notes that don't fit anywhere else should go here.
+   90% of the time, notes, warnings or cautions are better placed in the
+   parameters section. Consider that before using this section!
+  &lt;/para&gt;
+ &lt;/refsect1&gt;
+ 
  &lt;refsect1 role="seealso"&gt;
   &amp;reftitle.seealso;
   &lt;para&gt;
@@ -653,7 +673,7 @@
     <title>A <filename>reference.xml</filename> skeleton</title>
     <programlisting role="xml">
 &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
-&lt;!-- $Revision: 1.61 $ --&gt;
+&lt;!-- $Revision: 1.62 $ --&gt;
 &lt;!-- Purpose: xx --&gt;
 &lt;!-- Membership: xx --&gt;
 &lt;!-- State: xx --&gt;
@@ -723,7 +743,7 @@
     <title>A <filename>configure.xml</filename> skeleton</title>
     <programlisting role="xml">
 &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
-&lt;!-- $Revision: 1.61 $ --&gt;
+&lt;!-- $Revision: 1.62 $ --&gt;
 &lt;section id="extname.installation"&gt;
  &amp;reftitle.install;
  &lt;para&gt;
@@ -764,7 +784,7 @@
     <title>A <filename>constants.xml</filename> skeleton</title>
     <programlisting role="xml">
 &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
-&lt;!-- $Revision: 1.61 $ --&gt;
+&lt;!-- $Revision: 1.62 $ --&gt;
 &lt;section id="extname.constants"&gt;
  &amp;reftitle.constants;
  &amp;extension.constants;
@@ -814,7 +834,7 @@
     <title>A <filename>ini.xml</filename> skeleton</title>
     <programlisting role="xml">
 &lt;?xml version="1.0" encoding="iso-8859-1"?&gt;
-&lt;!-- $Revision: 1.61 $ --&gt;
+&lt;!-- $Revision: 1.62 $ --&gt;
 &lt;section id="extname.configuration"&gt;
  &amp;reftitle.runtime;
  &amp;extension.runtime;