This is an old revision of the document!
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:
$ cd phpdoc/scripts/docgen $ php docgen.php --help $ php docgen.php --output tmp --extension extname
This will create a directory named 'tmp' for the extension named 'extname' which will be full of documentation skeletons. 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 (firstname.lastname@example.org) and put in the request. While doing this, show the created documentation and eventually karma will be granted.
- Docgen may be used to generate specific documentation too, like for individual classes and functions
- Because the documentation generator utilizes Reflection to generate the skeletons, so it's important that proper arginfo exists within the source code