====Writing PECL Documentation====

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 CVS module named 'phpdoc' as this contains all PHP Documentation
  * Read the README found within phpdoc for a quick overview of how these docs work
  * Generate the documentation skeletons like so:

<code>
$ cd phpdoc/scripts/docgen
$ php docgen.php --help
$ php docgen.php --output tmp --extension extname --pecl
</code>

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 [[doc:scratchpad:howto|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.

==== What the PECL extension requires ====
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:
<code>
ZEND_BEGIN_ARG_INFO_EX(arginfo_count, 0, 0, 1)
	ZEND_ARG_INFO(0, var)
	ZEND_ARG_INFO(0, mode)
ZEND_END_ARG_INFO()
</code>

Which provides Reflection the information, so:

<code>
$ php --rf count

Function [ <internal:standard> function count ] {

 - Parameters [2] {
   Parameter #0 [ <required> $var ]
   Parameter #1 [ <optional> $mode ]
 }
}
</code>
==== Other Notes ====
  * 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