On Jun 5, 2009, at 12:11 AM, Hannes Magnusson wrote:
On Fri, Jun 5, 2009 at 01:00, Philip Olson<[email protected]> wrote:
Hello everyone,
Today I played around with the xhprof extension:
http://pecl.php.net/xhprof
It's nice, but lacks official documentation. Let's discuss how we
document
extensions that include optional helper libraries, so for example:
xhprof --> xhprof UI
inclued --> graphviz.php
ext/phar bundles command line application called "phar" which has
massive amount of options and stuff.
pecl/apc bundles apc.php.. (doesn't really need docs?)
Good example. Last week I learned that the phar command exists, and am
unsure how best to document it. In the very least we can mention 'phar
help' and briefly list the commands. It might look similar to how we
document CLI[1] but I'm unsure how redundant it might get, but maybe
most commands can simply link to a phar methods current documentation.
As for apc.php, another good example. The APC documentation briefly
mentions it but some sort of standard might help with all of these.
Awhile back memcache added something similar (memcache.php) although
it does not appear mentioned in the documentation.
Basically it comes down to the following options (please also think
of
others):
A) Suggest the helper be a PEAR package (PEAR Manual)
B) Simply add examples of its use in the PHP manual
C) Determine DocBook syntax, and fully document it within the PHP
manual
I have always seen the extension docs on php.net as API docs, with
usage examples and maybe basic tutorials.
Documenting applications using the extension / helpers feels a bit out
of scope to me.
I recently found out about the 'phar' command which is bundled as of
PHP5.3.0. It doesn't seem to have any test cases whatsoever and the
whole thing seems very weird to me.
If we start documenting these things too we cannot really create basic
skeletons that covers all possible applications and helpers so
consistency is almost out the window right away.
If these things end up being documented here then I think we should
just allow the individual authors to come up with their own structure
(obviously helping them along the way).
This all sounds reasonable, although I'm guessing whichever is
documented first will be copied. Let's make APC the first, and include
a couple of images. Today I envision us simply adding an example
section within the associated book that briefly shows its use.
Regards,
Philip
[1] http://php.net/features.commandline
