philip Tue Jul 27 02:24:12 2004 EDT
Modified files:
/phpdoc/howto working.xml
Log:
Added draft for new doc skeleton style, in the form of an example.
Please review, this is simply a draft (do not implement!)
http://cvs.php.net/diff.php/phpdoc/howto/working.xml?r1=1.41&r2=1.42&ty=u
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.41 phpdoc/howto/working.xml:1.42
--- phpdoc/howto/working.xml:1.41 Wed Jul 21 03:41:32 2004
+++ phpdoc/howto/working.xml Tue Jul 27 02:24:12 2004
@@ -640,6 +640,154 @@
mailing list</link>. If you have any suggestions for more skeletons do not
hesitate.
</para>
+ <para>
+ And we're introducing a new doc skeleton where multiple refsect1's are
+ used, as well as a lot more entities. Names in ALLCAPS would be changed
+ so for example RETURNTYPE would instead be bool, string, etc. Here's a
+ draft using example_func() as an example. <emphasis>Do not implement this
+ style yet!</emphasis> There are also reftitles for classes, constructors,
+ and methods. An OOP doc skeleton will be written in the future.
+ reftitles are located in <filename>language-defs.ent</filename>.
+ </para>
+ <para>
+ <example>
+ <title>An example example using refsect1's and reftitle entities</title>
+ <programlisting>
+<refentry id="function.example-func">
+ <refnamediv>
+ <refname>example_func</refname>
+ <refpurpose>Displays how to write a function man page, no ending period
here</refpurpose>
+ </refnamediv>
+ <refsect1>
+ &reftitle.description;
+ <methodsynopsis>
+
<type>RETURNTYPE</type><methodname>example_func</methodname>
+
<methodparam><type>ARGTYPE1</type><parameter>ARGNAME1</parameter></methodparam>
+
<methodparam><type>ARGTYPE2</type><parameter>ARGNAME2</parameter></methodparam>
+ <!-- parameter takes on a referenced variable -->
+
<methodparam><type>ARGTYPE2</type><parameter>&amp;ARGNAME2</parameter></methodparam>
+ <!-- optional parameter -->
+ <methodparam
choice='opt'><type>ARGTYPE3</type><parameter>ARGNAME3</parameter></methodparam>
+ <!-- optional parameter with default value, choice='opt' is default in this
case -->
+ <methodparam>
+ <type>ARGTYPE3</type>
+ <parameter>ARGNAME3</parameter>
+ <initializer>DEFAULTVALUE</initializter>
+ </methodparam>
+ <!-- Or, use <void /> if the function has no parameters at all -->
+ </methodsynopsis>
+ <simpara>
+ We are still in the description section. The description includes
+ information about the function, like what it does. This document is no
+ more than 78 characters in width except for the methodsynopsis. No tabs!
+ And only use unix-style line endings.
+ </simpara>
+ <para>
+ To continue on with our description we document parameter changes although
+ this may have it's own section in the near future.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ &reftitle.returnvalues;
+ <simpara>
+ This section describes return values. If the function simply returns
+ TRUE on success and FALSE on failure, simply use the &return.success;
+ entity here (this entity does not contain it's own para) otherwise describe
+ what the function returns in all cases. Also, there are &true; and
+ &false; entities.
+ </simpara>
+ </refsect1>
+
+ <refsect1>
+ &reftitle.examples;
+ <para>
+ Words may go here, but most likely not. Your example must meet the PEAR
+ Coding standards.
+ <example>
+ <title>An <function>example_func<function>example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+/* Use a role="php" only for PHP codes. See <screen>
+ * and other DocBook elements to express other
+ * types of listings. Use other role attributes for
+ * other type of programlistings, like: sql, httpd, ini,
+ * shell or http, as dictated by the example type.
+ */
+
+/* Do all indentation with spaces, not tabs, just to be sure.
+ * Don't try pushing the code to the right by adding spaces in
+ * front, this is the style sheet's job.
+ *
+ * All examples must meet the PEAR Coding Standard
+ */
+
+// a function example
+function some_code($foo)
+{
+ // use four spaces of indentation
+}
+
+// an example of bracket usage and spacing, always use
+// brackets, even when they are physically not needed
+if (some_code($foo) == 'foo') {
+ echo 'foo';
+} elseif (some_code($foo) == 'bar') {
+ echo 'bar';
+} else {
+ echo 'No foo, no bar';
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ Words may go here, but most likely not. Notice the use of the &listendand;
+ entity below, and how the functions are listed as one function per line.
+ There are no ending periods for see also's (or are there?).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ &reftitle.seealso;
+ <simpara>
+ <function>somefunc</function>,
+ <function>someother_func</function>&listendand;
+ <function>yetanotherfunc</function>
+ </simpara>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"../../../../manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ For parts we have no skeleton here, please look at existing files in the
+ <filename>phpdoc</filename> CVS module. If you are not sure a specific file
+ is good for a start, please ask on the <link linkend="chapter-maillist">phpdoc
+ mailing list</link>. If you have any suggestions for more skeletons do not
+ hesitate.
+ </para>
</chapter>
<chapter id="chapter-translation">
@@ -1412,4 +1560,4 @@
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
--->
+-->
\ No newline at end of file
