> http://livedocs.homelinux.com/en/function.mysqli-connect.html
>
> Instead of having each parameter in a paragraph, should we be adopting a
> more rigid varlist approach?
>
> For example: http://pear.php.net/manual/en/package.mail.mail.send.php
Agreed, this is the perfect time to bring this up. The following
is from the phpdoc TODO:
- consider adding beautified table for parameter definitions
and meanings. do this one extension at a time.
- see: http://marc.theaimsgroup.com/?l=phpdoc&m=103658209317795
Whether we simply use a <table>, <para role="...">, or a varlisting
is the main question here; that and how this will integrate with the
changelog.
Here are a few functions that demonstrate these new possibilities (or
at least versions thereof):
<table>
http://www.php.net/setcookie
http://www.php.net/date
<varlisting>
http://www.php.net/xml-parse
I like both :) The table is nice because it has defined columns
while the varlisting is simple and clean. When asking a few others,
the opinions are rather split. One person brought up how varlisting
is nice because the parameter names are on their own row so they're
easy to find. As far as tables, whether we need more than two columns
could depend on the individual functions as many are pretty straight
forward and won't need examples or notes. Something else to keep in
mind is most functions have less than three parameters.
Granted the stylesheets will be however we choose but we still have
to decide. The tables would need additional cellpadding.
Hopefully someone has a convincing point (or two) on how this should
be done...I don't!
Regards,
Philip
