cvs: phpdoc / README

From: Date: Mon, 05 Feb 2001 00:56:51 +0000
Subject: cvs: phpdoc / README
Groups: php.doc 
Request: Send a blank email to phpdoc+get-969334164@lists.php.net to get a copy of this message
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>

« previous php.doc (#969334164) next »