> -----Original Message----- > From: Philip Olson [mailto:[EMAIL PROTECTED] > Sent: Sunday, February 11, 2007 7:10 AM > To: Rasmus Lerdorf > Cc: Ronald Chmara; Mehdi Achour; internals@lists.php.net; > phpdoc@lists.php.net > Subject: Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Improving > the documentation > Those ideas about doing more are nice because the DOC tag is > a good start but additional collaboration is needed. Part of > the documentation teams job can easily be organizing > information requests so the developers can work efficiently. > If that means, as suggested above, periodic updates then > we'll for sure do it. A few come to mind already. It's > exciting to see this thread blossom! I hope everyone feels > free to brainstorm... ALL ideas are welcome!
All ideas? With regard to missing examples, how about incorporating some of the unit tests? >From what I understand, one of the purposes of unit testing is to actually test the function/method and to make sure it still works after amendments to the code. So, if it is good enough for unit testing, how much effort is it to use them as an example? Admittedly, the bigger picture could be missing. So, as developers want to write code (in preference to writing documentation), if they were able to provide working examples, rather than wordy documentation, at least there would be some PHP (rather than C) code available for the documentors to see what is going on and how things work. I assume the developers test their own code so they must have SOME PHP examples. If these where named according to something like this ... /php-src/ext/module/examples/function_nn.php /php-src/ext/module/examples/extension_nn.php Where : ext is the name of the extension, function is the name of the function or method, nn is a simple count (01, 02, 03, etc) extension is for more global examples that would appear on the ext's main page rather than on a function/method page.... These examples COULD include a tag or a comment for versioning. The idea here is to allow the developers to show the world using PHP what their extension does. They say a picture is worth a thousand words. I think, in some cases, an example would also work. Ideally, the examples should also include some output (that's the hard part) so the example could be cut'n'pasted and tested and the user could see that the output matches. A little bit sort of like a unit test. Then the documentation team could see proper/expected usage. It COULD also make more unit tests available. If the developers primary language is NOT English, then that's not an issue as the PHP language would be the common denominator. By having the examples as separate files, they could actually be tested to make sure they work (not exactly sure how to automate this). Capturing output could also be done automatically. Image function examples could create the images used for the manual, etc. The possibilities are endless. And the start point is to get developers to write a little bit more code rather than writing documentation. Regards, Richard Quadling. -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php
