doc:howto:pecldocs
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision | ||
doc:howto:pecldocs [2009/10/16 20:40] – expanded arginfo example philip | doc:howto:pecldocs [2014/06/20 12:23] – replaced with a new guide sobak | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | + | This page has been removed, in favor of [[http:// | |
- | ====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 | + | |
- | + | ||
- | * Load the PECL extension into PHP CLI. | + | |
- | * Checkout the SVN modules, namely phpdoc/en and phpdoc/ | + | |
- | * 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/ | + | |
- | $ php docgen.php --help | + | |
- | $ php docgen.php --output tmp --extension extname --pecl | + | |
- | </ | + | |
- | + | ||
- | This will create a directory named ' | + | |
- | + | ||
- | * Read the Validating Changes section of the [[doc: | + | |
- | * 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: | + | |
- | < | + | |
- | /* Definition of the arginfo */ | + | |
- | ZEND_BEGIN_ARG_INFO_EX(arginfo_count, | + | |
- | ZEND_ARG_INFO(0, | + | |
- | ZEND_ARG_INFO(0, | + | |
- | ZEND_END_ARG_INFO() | + | |
- | + | ||
- | /* Implement it */ | + | |
- | zend_function_entry basic_functions[] = { | + | |
- | PHP_FE(count, | + | |
- | {NULL, NULL, NULL} | + | |
- | }; | + | |
- | </ | + | |
- | + | ||
- | Which eventually provides Reflection the information, | + | |
- | + | ||
- | < | + | |
- | $ php --rf count | + | |
- | + | ||
- | Function [ < | + | |
- | + | ||
- | - Parameters [2] { | + | |
- | | + | |
- | | + | |
- | } | + | |
- | } | + | |
- | </ | + | |
- | + | ||
- | ==== Other Notes ==== | + | |
- | * Docgen may be used to generate specific documentation too, like for individual classes and functions | + | |
- | * Write in third person voice (no " | + | |
- | * XML is single spaced | + | |
- | * Don't commit skeletons and "fill them out later", | + | |
- | * 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/ | + |
doc/howto/pecldocs.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1