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

[Derick Rethans]

derick          Fri Jun 20 11:39:00 2003 EDT

  Modified files:              
    /phpdoc/howto       working.xml 
  Log:
  - Some more guidelines:
    - note, tip and caution usage
    - commenting usage
  - Fixed misplaced note in example example
  
  
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.33 phpdoc/howto/working.xml:1.34
--- phpdoc/howto/working.xml:1.33       Fri Jun 20 11:05:56 2003
+++ phpdoc/howto/working.xml    Fri Jun 20 11:39:00 2003
@@ -157,27 +157,19 @@
      <literal>&lt;</literal> to <literal>&amp;lt;</literal>, etc.
      Examples look much better, and easily manageable.
     </simpara></listitem>
+
     <listitem><simpara>
      Deprecated aliases and syntax should not be used in examples.
     </simpara></listitem>
 
-    <listitem><para>
-     If an example uses arguments specific to a newer version of
-     PHP, it is helpful to note this in the example:
-     <programlisting role="php">
-foo("bar", "baz"); // second argument was added in PHP 4.0.3
-     </programlisting>
-     New arguments are denoted in the main text of the
-     entry using the form:
-     <programlisting>
-<![CDATA[
-<note>
- <simpara>
-  The second parameter was added in PHP 4.0.3.
- </simpara>
-</note>
-]]>
-      </programlisting>
+    <listitem>
+     <simpara>
+      Use the &lt;note> when a function is not available in some special
+      cases, or when the parameter list of a function has changed, but not for
+      every little thing like mentioning that the function also can accept
+      'foo' instead of 'bar' as value to a parameter. Use notes with care.
+     </simpara>
+     <simpara>
       Make sure note elements are always children of the main element in a
       file, unless the note belongs to a specific item in the text, such as an
       example:
@@ -191,17 +183,69 @@
      The output is:
     </para>
     <screen />
+    <note>
+     <simpara>
+      This example only works on Unices.
+     </simpara>
+    </note>
    </example>
-   <note>
-    <simpara>
-     This example only works on Unices.
-    </simpara>
-   </note>
   </para>
 ]]>
       </programlisting>
-    </para></listitem>
+     </simpara>
+
+     <simpara>
+      If there is something dangerous to document such as the
+      <function>chroot</function>, or when something can be seen as a
+      weirdness in the language such as weird autoconversion of types, use the
+      &lt;caution> element.
+     </simpara>
+     <simpara>
+      The &lt;tip> can be used in cases where you might want to document a
+      performance issue.
+     </simpara>
+    </listitem>
+
+    <listitem>
+     <simpara>
+      For comments in example, use <literal>//</literal> for single line
+      comments (preferable above the lines of code the comment comments on),
+      and use <literal>/* .. */</literal> for multiline comments:
+      <programlisting role="xml">
+<![CDATA[
+<programlisting role="php">
+// This line execute foo
+foo();
+
+/* The next few lines also execute foo, but in a
+ * weird way */
+$var = 'foo';
+$var();
+</programlisting>
+]]>
+      </programlisting>
+     </simpara>
+    </listitem>
 
+    <listitem><para>
+     If an example uses arguments specific to a newer version of
+     PHP, it is helpful to note this in the example:
+     <programlisting role="php">
+foo("bar", "baz"); // second argument was added in PHP 4.0.3
+     </programlisting>
+     New arguments are denoted in the main text of the
+     entry using the form:
+     <programlisting role="xml">
+<![CDATA[
+<note>
+ <simpara>
+  The second parameter was added in PHP 4.0.3.
+ </simpara>
+</note>
+]]>
+     </programlisting>
+    </para></listitem>
+      
     <listitem><simpara>
      The language constants true, false and null
      should be written as <literal>&amp;true;</literal>,



-- 
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php