> It seems to be that a lot of the time, the documentation on the website is > out of step with the latest release of PHP. In almost all of these cases, > PHP is at version X, and the online docs are describing version X+1, or the > CVS version. > > Case in point: the DOMXML extension is now much better documented, but none > of the functions listed apply to PHP 4.1.2. Furthermore, all the DOMXML > functions that *are* in PHP 4.1.2 have been dropped from the documentation > in favour of (what I assume) are the new 4.2.0 functions. > > Can the documentation folks use release tags like the dev folks do? For > instance, when PHP 4.2.0 is release, make a PHP_4_2_0 branch in CVS for the > docs. The website docs get built using that branch. Any changes to the > *current* docs (spelling changes, etc.) get made on that branch, but any new > docs that reflect PHP 4.3.0 are made on the HEAD branch. Then, when 4.3.0 > is released, make a PHP_4_3_0 tag, and change the scripts to generate the > online docs to use that branch. Rinse and repeat.
Something like this problem was discussed on our meeting at Stuttgart. We came up with the idea of including a "Changelog" on all function pages where it is needed. We can't freeze the docs for specific PHP versions as we often discover undocumented features let's say, from PHP 4.0.0... That means that we have documented behaviour of functions only available in CVS, but often we have no updated documentation for some functions which changed their behaviours releases before. Our documentation is dinamicaly changing in all directions... Goba
