Conventions
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 (-).
- 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.
- 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.
- 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
New arguments are denoted in the main text of the entry using the form:
- 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).
- In prototypes, you can also use mixed (various types), or number (either integer or float), or scalar (boolean, integer, float or string). A callback is denoted as mixed [1], since it can be either array or string.
- 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 Doc Book 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.
