Documenting PECL module containing a single function

From: Date: Fri, 09 Jan 2009 19:41:03 +0000
Subject: Documenting PECL module containing a single function
Groups: php.doc php.pecl.dev 
Request: Send a blank email to phpdoc+get-969379990@lists.php.net to get a copy of this message
Hello all, I have been asking myself this question for quite a long time, and recently received emails about non-documented PECL modules. My dilemna here is how should we document a PECL module that only contains 1 function. For the sake of the discussion, I'm talking about the Double Metaphone PECL package that creates the function double_metaphone(). PHP already contains the metaphone() function in the core, this is an enhancement supporting more languages than just English. Now, I see a couple of options here: 1) Document the function and put it along the metaphone() ref doc in the Strings category. This is confusing, since this is not a core function and only available when installing the PECL package. However, each page has a version info on top, and it would say in that case: "PECL version > x.x.x" 2) Create a Double Metaphone section, having almost nothing except how to install the extension (default entities here) plus the function documentation in it. It feels a little weird having a whole section with only one function though. 3) Move the double_metaphone() function inside core as a sister function to metaphone() and document as usual. I'm not a big fan of this, but if it's the way to go, I can move the extension. Any comments welcomed. Regards, Olivier -- http://www.olivierhill.ca/

« previous php.doc (#969379990) next »