Morning All,
Further to discussion in IRC this morning, I'd like to propose what
amounts to, I guess, a sub-project to properly document everything,
starting with everything declared ZEND_API in /Zend.
We put a lot of effort into the generation and maintenance of user land
documentation, but there are only scraps of information here and there,
and then ... the accepted way of working with the source is lxr and lots
and lots of reading, which is fine, if you require intricate knowledge
of every part of the API you are interacting with, which normally you do
not, usually it is enough to know of it's existence, it's usage and
implementation is either obvious or irrelevant in the vast majority of
cases, should the function prototype be documented.
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.
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
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 ??
Thanks for listening :)
Joe
Morning All,
Further to discussion in IRC this morning, I'd like to proposewhat amounts to, I guess, a sub-project to properly document everything,
starting with everything declared ZEND_API in /Zend.We put a lot of effort into the generation and maintenance of userland documentation, but there are only scraps of information here and
there, and then ... the accepted way of working with the source is lxr and
lots and lots of reading, which is fine, if you require intricate knowledge
of every part of the API you are interacting with, which normally you do
not, usually it is enough to know of it's existence, it's usage and
implementation is either obvious or irrelevant in the vast majority of
cases, should the function prototype be documented.I am also aware of some documentation included in the PHP manualcurrently, which should also be completed, and included, with all of the
API in a searchable format, just like PHP is in userland.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
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 ofhands, who can actually help ??
Thanks for listening :)
Joe
--
Hi,
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.
Keeping it up-to-date would be less of a problem, as we could put the
burden of updating the docs on that person changing the code.
Personally I think it would be nice if we could have inline comments in the
code, and using doxygen (or similar) tool to generate some html
representation for the docs (helly used this for documenting spl:
http://www.php.net/~helly/php/ext/spl/ ).
But we also need to have some more high level documentation, where we
introduce the concepts and how the pieces fit together, that could be under
http://php.net/internals2
I'm curious what others think though.
--
Ferenc Kovács
@Tyr43l - http://tyrael.hu
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
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
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 ...
I don't want to be a party pooper, but we have enough problems of
documenting userland php-src that documenting the internals would
simply never be able to keep up with changes/additions, so always be
incomplete. Not to mention the fact it is gigantic work to even do the
initial docs, and maintaining them no less of a work :)
I would love to get the header files commented, like you seem to be
proposing (which is confusing, do we really need to ask to add
comments? Or an RFC? :)).
And adding header files like Sara proposed the other day, with
extensive comments, is definitively the way to go.
Once the header files are properly documented and understandable by
extension writers we could look into ways of embedding that in the
online manual somehow.
-Hannes
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
Hi!
I'm not really sure how documenting (inline) API functions is really
going to be any different to the prototypes we all put on extension
functions/methods, or any more time consuming, and I don't see how
randomness comes into it.Just listing function args is not enough usually - in the manual,
functions that have just protos are almost as good as undocumented. I of
course have a bit of skewed point of view - for me, proto is not needed
for API function because I can just look up the function definition
right in the source. But maybe for somebody it would be helpful.I understand having no time but then these are files we all read and
work with, I don't really understand not being able to take an extra 5
minutes here and there when we are already engaged in working with the
source.It's not the question of ability, it's the question of a) if it's useful
and b) having accepted format for doing it.
Stas,
It is useful if we define the accepted format and encourage people
to include useful information, clearly you can look at a function and
know it's prototype immediately, but there's no way you know of all 1000
functions, how on earth do you search for a function you do not even
know exists.
Assuming you find it, which 800/1000 times you will not, reading a
prototype doesn't give you all the information you need, it doesn't give
you anything. You always end up having to read the source code, where it
could be explained in one/two English sentence(s) which your eyes can
process at the same time as reading the prototype itself ...
I cannot believe it's taken so much discussion just to get nowhere,
all I wanted was for someone to take the lead and say "use this
standard/format/software", "you may/may not edit headers", "we will
deploy the documentation at http://"; ... I give up ...
hi,
It is useful if we define the accepted format and encourage people toinclude useful information, clearly you can look at a function and know it's
prototype immediately, but there's no way you know of all 1000 functions,
how on earth do you search for a function you do not even know exists.
Assuming you find it, which 800/1000 times you will not, reading a
prototype doesn't give you all the information you need, it doesn't give you
anything. You always end up having to read the source code, where it could
be explained in one/two English sentence(s) which your eyes can process at
the same time as reading the prototype itself ...I cannot believe it's taken so much discussion just to get nowhere, allI wanted was for someone to take the lead and say "use this
standard/format/software", "you may/may not edit headers", "we will deploy
the documentation at http://"; ... I give up ...
The more I look at this problem (and have looked at it quite a lot of
time), the more I think we should enforce one tool for inline
docblock. Doxygen or other (I use cxref, small and perfect for C)
would do it, generate docs on release/snaps and be done with that. But
the current situation simply increases the clue gap between those
implementing internal functions and those using them. Btw, I do not
blame anyone, we are all lazy, and I am the laziest :)
Cheers,
Pierre
@pierrejoye
Morning All,
Further to discussion in IRC this morning, I'd like to propose whatamounts to, I guess, a sub-project to properly document everything,
starting with everything declared ZEND_API in /Zend.We put a lot of effort into the generation and maintenance of userland documentation, but there are only scraps of information here and
there, and then ... the accepted way of working with the source is lxr
and lots and lots of reading, which is fine, if you require intricate
knowledge of every part of the API you are interacting with, which
normally you do not, usually it is enough to know of it's existence,
it's usage and implementation is either obvious or irrelevant in the
vast majority of cases, should the function prototype be documented.I am also aware of some documentation included in the PHP manualcurrently, which should also be completed, and included, with all of the
API in a searchable format, just like PHP is in userland.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 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 ofhands, who can actually help ??
Thanks for listening :)
Joe
There seems to be a kind of focus on the things we all know about,
understandably.
To clarify, I do not mean that we should document hashtable and objects
and call it a day, I mean that there is more than 1000 exported ZEND_API
or PHPAPI functions in the source code this evening ... here's a list:
Drop the scrollbar anywhere random, have you written what you land on
more than once ?? Think it's probably worth the time now ?? Surely
writing extensions and developing patches and ideas would become much
easier if this knowledge was easily accessible and documented, surely
you'll get the time back you put in 10 fold ??
Food for thought ....
Nite ...