PECL documentation is stored within the official PHP Manual, and while releasing a PECL extension it's important to publish documentation to allow users to find and know how to use the extension, and easily allow others to contribute to these docs.

The process of writing documentation is as follows:

• Load the PECL extension into PHP CLI.
• Checkout the SVN modules, namely phpdoc/en and phpdoc/doc-base. For how, see: checkout
• Read the README found within phpdoc for a quick overview of how these docs work
• Generate the documentation skeletons like so:

$ cd phpdoc/doc-base/scripts/docgen
$ php docgen.php --help
$ php docgen.php --output tmp --extension extname --pecl

This will create a directory named 'tmp' that will contain documentation skeletons for the 'pecl' extension named 'extname'. Reflection is used to make guesses about the extension, like for classes, methods, functions, constants, parameters, version information, etc. but this information will not be fully correct. Please go through and edit each XML file by updating this information and adding documentation.

• Read the Validating Changes section of the PHP Documentation HOWTO.
• Once validated, commit this documentation.

If the user account lacks phpdoc karma, write the documentation list (phpdoc@lists.php.net) and put in the request. While doing this, show the created documentation and eventually karma will be granted.

Because docgen utilizes Reflection to create the skeletons, it's necessary for the extensions code to use arginfo structs to provide parameter information.

For example, the count() source code has this:

/* Definition of the arginfo */
ZEND_BEGIN_ARG_INFO_EX(arginfo_count, 0, 0, 1)
	ZEND_ARG_INFO(0, var)
	ZEND_ARG_INFO(0, mode)
ZEND_END_ARG_INFO()

/* Implement it */
zend_function_entry basic_functions[] = {
        PHP_FE(count, arginfo_count),
        {NULL, NULL, NULL}
};

Which eventually provides Reflection the information, so:

$ php --rf count

Function [ <internal:standard> function count ] {

 - Parameters [2] {
   Parameter #0 [ <required> $var ]
   Parameter #1 [ <optional> $mode ]
 }
}

Need more information? Here's a rough draft that will one day find itself within the official documentation.

• Docgen may be used to generate specific documentation too, like for individual classes and functions
• Write in third person voice (no “You”)
• XML is single spaced
• Don't commit skeletons and “fill them out later”, commit them when they are filled out
• Skeletons generate several sections that you may not use, such as examples and errors… in this case delete them
• Don't commit auto-generated files from build time (like entities.*)
• Feel free to ask phpdoc@lists.php.net for code review, or #php.doc on Efnet
• When testing, be sure to add to manual.xml.in in phpdoc/ otherwise it won't be validated/tested/built
• When adding documentation to an already documented extension, the –copy and –phpdoc directives are used to copy only new docs over
• Use –seealso to add skeleton SeeAlso roles, and –example to add skeleton Example roles (and adds a examples.xml).
• Use –test to enter test mode, which affects a few things like when enabled, –copy will print what it would have copied