Re: Proposal to document all of Zend and PHP API and SAPI layers

Hi! > 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. That is a good idea. Do it :) > 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 Inline probably wouldn't work that well. To make API understandable, there is a need in substantial narrative description, which is poorly compatible with the layout of the source code. Just sticking it in random place in the sources does not seem beneficial - I think it is better to have these in central place. Many individual functions become very easy to figure out once you understand the picture of the API - i.e., once you know how the HashTable API works, you don't need a lot of docs to understand what zend_hash_exists() does. So while it may make sense to describe some complex piece of code inline, describing the API usually works better separately, IMHO. > 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 ?? Depends on what you mean by "help". If you need somebody who can answer occasional questions on how something works - I think many people on this list could do it. I wouldn't mind doing it. If you mean actually formatting, writing and maintaining docs in proper order - I wouldn't volunteer for such project since I probably would never have enough time. It is a significant effort which will need a lot of time, one of the reasons probably why it wasn't done yet. -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/ (408)454-6900 ext. 227