Morning All,
Further to discussion in IRC this morning, I'd like to propose what
amounts to, I guess, a sub-project to properly document everything,
starting with everything declared ZEND_API in /Zend.
We put a lot of effort into the generation and maintenance of user land
documentation, but there are only scraps of information here and there,
and then ... the accepted way of working with the source is lxr and lots
and lots of reading, which is fine, if you require intricate knowledge
of every part of the API you are interacting with, which normally you do
not, usually it is enough to know of it's existence, it's usage and
implementation is either obvious or irrelevant in the vast majority of
cases, should the function prototype be documented.
I am also aware of some documentation included in the PHP manual
currently, which should also be completed, and included, with all of the
API in a searchable format, just like PHP is in userland.
Ideally, it would be nice to document the API inline, in source, this
means disturbing lots of files, which I'm not keen on, if anyone has any
ideas, speak up. The benefit of inline documentation is that if a
function is changed the changer has the documentation in their
peripheral vision, and the chances of documentation getting stale are
less likely than if they have to document using some separate system.
I'd like to gauge reaction to this idea, and with it a show of hands,
who can actually help ??
Thanks for listening :)
Joe
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
