Documenting PECL module containing a single function
| From: | Olivier Hill | 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/