分类：
2008-05-27 22:05:54
几个关键的文件：
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 (
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 form instead of . Use 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
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:
|
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
The
For comments in example, use // for single line comments (preferable above the lines of code the comment comments on), and use /* .. */ for multiline comments:
|
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 |
|
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 comment as the second line after the 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
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
Document examples always with the following structure:
|
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 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]
