doc:scratchpad:pecldocs

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

doc:scratchpad:pecldocs [2008/12/04 23:40]
philip expand arginfo notes, as per felipe's email
doc:scratchpad:pecldocs [2017/09/22 13:28]
Line 1: Line 1:
- 
-====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 
-</code> 
- 
-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 [[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 
  
doc/scratchpad/pecldocs.txt · Last modified: 2017/09/22 13:28 (external edit)