ronabop Sun Feb 4 16:56:51 2001 EDT
Modified files:
/phpdoc README
Log:
Updated for closing XML tags, bracketing, using current names, etc.
Index: phpdoc/README
diff -u phpdoc/README:1.9 phpdoc/README:1.10
--- phpdoc/README:1.9 Fri Jan 5 20:28:13 2001
+++ phpdoc/README Sun Feb 4 16:56:50 2001
@@ -38,7 +38,8 @@
as part, chapter, sect1 etc. The HTML stylesheet will
name the HTML files after these IDs.
- 2. Function reference IDs look like this (case does not matter):
+ 2. Function reference IDs look like this (case should be consistent
+ with the rest of the function naming standards, i.e. lowercase):
`function.imageloadfont'. Please note that underscores cannot
be used in IDs, they should be replaced by minus signs (-).
@@ -54,6 +55,15 @@
converting from sgml-tools. For normal function reference, the
text "Description" should be used instead of the function name.
+ 7. Bracketing and naming conventions in examples should adhere to
+ other examples in the manual, and standards for function names.
+ Deprecated aliases and syntax should not be used in examples.
+
+ 8. If an example of using arguments specific to a newer version of
+ php, it is helpful to note that in the example:
+
+ foo_function_exec ("bar", "baz"); // second argument was added in PHP 4.0.3
+
WHAT TO DOCUMENT
1. Only major functions should be documented, functions which are
@@ -154,13 +164,15 @@
<funcdef>RETURNTYPE <function>FUNCTIONNAME</function></funcdef>
<paramdef>ARGTYPE1 <parameter>ARGNAME1</parameter></paramdef>
<paramdef>ARGTYPE2 <parameter>ARGNAME2</parameter></paramdef>
- <paramdef>ARGTYPE3
<parameter><optional>ARGNAME3</optional></parameter></paramdef>
+ <paramdef>ARGTYPE3
+ <parameter><optional>ARGNAME3</optional></parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<simpara>
A simple paragraph that can not contain anything that requires
fancy layout.
-
+ </simpara>
<para>
A normal paragraph that can contain lots of stuff. For example
<example>
@@ -170,48 +182,69 @@
* Don't try pushing the code to the right by adding spaces in
* front, this is the style sheet's job.
*/
+
+// a function example
function some_code($foo)
{
/* we all agree that four spaces of indentation is good? */
}
-</programlisting></example>
+// an example of bracket usage and spacing
+if (some_code($foo) == "foo") {
+ echo "foo";
+} elseif (some_code($foo) == "bar") {
+ echo "bar";
+} else {
+ echo "No foo, no bar";
+}
+ </programlisting>
+ </example>
+
The text in a paragraph may continue after the example as well.
Here is how to make lists:
<itemizedlist>
-
- <listitem><simpara>
+ <listitem>
+ <simpara>
List items must contain a container element such as
simpara or para (there are plenty of others too, see the
DocBook reference for the listitem element.
+ </simpara>
+ </listitem>
- <listitem><simpara>
+ <listitem>
+ <simpara>
List items must contain simple paragraphs or paragraphs.
-
- <listitem><para>
+ </simpara>
+ </listitem>
+ </itemizedlist>
+
+ <itemizedlist>
+ <listitem>
+ <para>
If you plan on making sub-lists, you must use para
-
<orderedlist>
- <listitem><simpara> first list item
- <listitem><simpara> second list item
+ <listitem><simpara> first list item</simpara></listitem>
+ <listitem><simpara> second list item</simpara></listitem>
+ You can also continue an ordered list you just left off
</orderedlist>
-
- You can also continue an ordered list you just left off
-
<orderedlist>
- <listitem><simpara> third list item
- <listitem><simpara> fourth list item
+ <listitem><simpara> third list item</simpara></listitem>
+ <listitem><simpara> fourth list item</simpara></listitem>
</orderedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </simpara>
<simpara>
The documentation for a function should be wrapped up with
a "See also" list like this:
-
+ </simpara>
<simpara>
See also <function>stripslashes</function> and
<function>quotemeta</function>.
-
+ </simpara>
</refsect1>
</refentry>
