When you work on phpdoc XML files, you should stick to these conventions, to ease the team work in the module.
Insert ID attributes in all major section tags such as part, chapter, sect1 etc. The HTML stylesheet will name the HTML files after these IDs.
Function reference IDs look like this (case should be consistent with the rest of the function naming standards, i.e. lowercase): function.mysql-connect. Please note that since underscores cannot be used in IDs, they should be replaced by minus signs (-).
Unlike function reference IDs method reference IDs are case-sensitive. Special operators ::, -> and underscores are replaced by the same minus signs (-). For example function.DOMCharacterData-deleteData is an ID for DOMCharacterData->deleteData and function.ArrayObject-constructor is for ArrayObject::__constructor method accordingly. Note an exception when operators :: and -> followed by two underscores are replaced with one minus sign (-).
Function reference section IDs (<reference id="...">) look like this: 'ref.category', for example: 'ref.ftp'.
Add PHP example code programlistings always with a role attribute set to "php". Never add any other programlisting or PHP output with such a role. It is reserved for PHP source code only. This role is used to detect PHP code and highlight it.
The contents of examples with programlistings start on column 0 in the XML code. Indenting, bracketing and naming conventions in examples should adhere to the PEAR coding standards.
All examples use the <?php ... ?> form instead of <? ... ?>. Use <![CDATA[ ... ]]> for examples, since it eliminates the need to change < to <, etc. Examples look much better, and easily manageable.
Deprecated aliases and syntax should not be used in examples.
Use the <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.
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:
<para>
<example>
<title />
<programlisting/>
<para>
The output is:
</para>
<screen />
<note>
<simpara>
This example only works on Unices.
</simpara>
</note>
</example>
</para> |
If there is something dangerous to document such as the chroot(), or when something can be seen as a weirdness in the language such as weird autoconversion of types, use the <caution> element.
The <tip> can be used in cases where you might want to document a performance issue.
For comments in example, use // for single line comments (preferable above the lines of code the comment comments on), and use /* .. */ for multiline comments:
<programlisting role="php"> // This line execute foo foo(); /* The next few lines also execute foo, but in a * weird way */ $var = 'foo'; $var(); </programlisting> |
If an example uses arguments specific to a newer version of PHP, it is helpful to note this in the example:
foo("bar", "baz"); // second argument was added in PHP 4.0.3 |
<note> <simpara> The second parameter was added in PHP 4.0.3. </simpara> </note> |
The language constants true, false and null should be written as &true;, &false; and &null;. There are other shortcuts, such as &php.ini;. These are stored in global.ent.
All English XML files should have a <!-- $Revision --> comment as the second line after the <?xml tag. This comment is not necessary for non-English files.
Whitespace changes in the English tree should be prevented as much as possible: it is more important to keep a good change-history of real changes, because of the translations. If a whitespace change is really needed, do it at least in a separate commit, with a clear comment such as 'WS fix' or 'Whitespace fix'.
Never use tabs, not even in example program listings. XML should be indented with one space character for each level of indentation; example code uses four spaces.
Always use LF (Line Feed) for the only newline character in files, this is the Unix standard. Never use CR LF (Windows) or CR (Mac) even, when editing Windows specific files (such as *.bat). It eases the editing works.
In the docs, the types are denoted as: boolean (bool in prototypes), integer (int in prototypes), float (not double!), array, object (not class!), resource and null (all lowercase). For objects different from stdClass, use the class name instead of object.
In prototypes, you can also use mixed (various types), or number (either integer or float). A callback is denoted as callback.
Do not use mixed, if the return value is of a certain (not boolean) type, and FALSE only on error. Provide the primary return type as the return type of the function, and write down in the explanation, that it returns FALSE on error. Use &return.success; if the function returns TRUE on success, and FALSE on failure.
If a function requires no arguments, use <void/> instead of <parameter>void</parameter>, since the former is the correct DocBook XML tag.
If a function has an undefined return-value, use the word void.
In a prototype, if there are multiple - really distinct - possibilities, simply make it two! See en/reference/math/functions/min.xml for an example.
Aliases: in refpurpose, put: Alias of <function>realfunc</function>. Do not specify a function prototype synopsis, and nothing but simply the text: This function is an alias of <function>realfunc</function>. This way, people can go to realfunc straight from the ref.foo page.
Document examples always with the following structure:
<para> <example> <title /> <programlisting> <![CDATA[ <?php echo "foo\n"; ?> ]]> </programlisting> <para> The output is: </para> <screen> <![CDATA[ foo ]]> </screen> </example> </para> |