On 04/05/2013 01:23 PM, Johannes Schlüter wrote:
On Fri, 2013-04-05 at 14:09 +0200, Ferenc Kovacs wrote:
I think that it everybody would support that idea, unfortunatelly not
many
people have the knowledge AND the time to write up that kind of
documentation.
That is the key part. There's no worse documentation than wrong
documentation. Maybe correct documentation only mentioning "useless"
information.
I also think that documenting each and every API leads nowhere, but as
Ferenc said we have to document the structure and help people tofind
what they need.
This all takes time, though, and many seem to prefer adding syntax sugar
and such things over fixing bugs and documenting things.
johannes
http://php.net/manual/en/internals2.php
This, would be brilliant, if it were anything like complete, and had a
searchable API reference, rather than an empty section labelled API
reference.
What I suggest is that we make an effort to properly define a way to
document the source code. Each in our own time we can document the
things we interact with, or pick a file whenever we have a spare ten
minutes.
We might not have a complete set of documentation until version 6 or
after, it might even never be complete, much like the PHP manual, but at
least it will be on the way, it shouldn't take long for everyone who
needs to be aware to become aware, and those that introduce new
prototypes or change old ones will know what is expected of them.
I shouldn't have said sub-project, what I should have said was, "I
propose that we define a standard way to document everything internal",
if there is a standard, and the people working on the source are (made)
aware of it, it is surely no effort at all to maintain it, once the
initial work is done, which doesn't have to happen yesterday.
Along with documenting source, we should of course complete the write up
of internals2 ...
Joe
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
