Only major functions should be documented; functions which are deprecated variants may be mentioned, but should not be documented as separate functions. They instead should be referenced in the parent function as an alias. Functions which have completely different names, however, should be documented as separate entries, for ease of reference. The aliases.xml appendix is the place to store aliases not documented elsewhere.
For example mysql_db_name and mysql_dbname will be documented as the same function, with the latter being listed as an alias of the former, while show_source and highlight_file will be documented as two different functions (one as an alias), as the names are completely different, and one name is not likely to be found if looking for the name of the other.
Function names should be created, and documented, in lowercase format with an underscore separating the name components. Names without underscores are often only kept for backward compatibility. Document the function named with underscores separating components, and mention the old one as an alias.
Note: It is up to the PHP developers to give names to functions. A PHP documentation writer only uses the name provided to document the function. If you think that a function name is not appropriate, open a discussion on the [email protected] list, by sending a mail to that address.
Good: mcrypt_enc_self_test, mysql_list_fields
OK: mcrypt_module_get_algo_supported_key_sizes (could be mcrypt_mod_get_algo_sup_key_sizes?), get_html_translation_table (could be html_get_trans_table?)
Bad: hw_GetObjectByQueryCollObj, pg_setclientencoding
Functions which are kept only for backwards compatibility should be listed under their current parent names, and not documented as separate functions. Backwards compatible functions and documentation for them should be maintained as long as the code can be reasonably kept as part of the PHP codebase. Also see the appendix aliases.xml.
Short but complete code examples are much more desirable than long ones. If a function is extremely complex, a suitable place to put a longer example is in the chapter introduction. This example can hold code for other functions in the same chapter.
Brevity is appreciated. Long-winded descriptions of each and every function are not appropriate for the reference sections. Using the errata comments as guidelines, it's easier to tell when more documentation is needed, as well as the inverse, when too much documentation in one section has increased confusion. [1]
| [1] | No one complained about too much documentation in any section until now, so be brave to add longer explanations, and more than one example per function. :) |