Hello internals,
I've been helping with PHP documentation for 4 years now, and I still
can't help the fact that a loooot of things are not documented, that
our/my way of handling the PHP documentation update is not accurate, nor
productive, nor bug free at all.
Personally, I try to follow commits on php.cvs, bug reports, Change
Log?, user notes on the online manual.. but I still have the feeling of
missing a lot of changes. After a year away from the project, I have
_no_ clue what was added, when, and whether it was added to our
documentation or not.
I know that you developers are willing to help a lot with it, but that
you cannot manage to save the spare time needed to do it the right way.
That's why I would like to propose a simple/small/timeless change in
your CVS commit messages: If you feel that the change need to be
documented, place the @doc keyword at the end of your message log entry.
And if you feel like telling us more about what you changed, point us to
some online resource or whatever. Simply add that after the @doc tag.
This additional comment is optional, and you don't need to bother if the
change is obvious, or if you simply don't feel like doing it ATM.
This small @doc tag could _slightly_ improve/optimize/sanitize our work
on the documentation. By adding some SQL logging in loginfo.pl, and
storing the following:
* date: commit date
* login: CVS account of the developer
* branch: CVS branch
* files: Changed files
* commit: Commit message before @doc
* desc : Optional developer description after @doc
We would be able to have an interface displaying a dynamic phpdoc TODO,
with some nice features like a search by PHP version, extension,
assignee, keywords..
Additionally, we can imagine adding an online help feature on the
interface, by setting a “help” flag on some hardly understandable
change, to have [EMAIL PROTECTED] notified of our need for enlightenment.
Any thoughts ?
Mehdi Achour
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
