# Proposal to document all of Zend and PHP API and SAPI layers

- Thread: https://externals.io/message/66973
- Original archive: https://news-web.php.net/php.internals/66973
- Started by Joe Watkins on 2013-04-05T11:00:55+00:00
- Messages: 9
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #66973 — Joe Watkins — 2013-04-05T11:00:55+00:00

URL: https://externals.io/message/66973#66973

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

---

## #66977 — Ferenc Kovacs — 2013-04-05T12:09:59+00:00

URL: https://externals.io/message/66973#66977 · In reply to: #66973

> 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
>
> --
> 
> 
>
>
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

---

## #66978 — johannes@schlueters.de — 2013-04-05T12:23:24+00:00

URL: https://externals.io/message/66973#66978 · In reply to: #66977

> 
> 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

---

## #66980 — Joe Watkins — 2013-04-05T12:48:40+00:00

URL: https://externals.io/message/66973#66980 · In reply to: #66978

> 
> > […]
>
> 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

---

## #66983 — Hannes Magnusson — 2013-04-05T13:16:28+00:00

URL: https://externals.io/message/66973#66983 · In reply to: #66980

> 
> > […]
>
> 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

---

## #66991 — Stas Malyshev — 2013-04-05T20:52:15+00:00

URL: https://externals.io/message/66973#66991 · In reply to: #66973

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

---

## #66992 — Joe Watkins — 2013-04-05T21:44:21+00:00

URL: https://externals.io/message/66973#66992 · In reply to: #66973

> 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

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:

http://pastebin.com/42xFsNQ0

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 ...

---

## #66996 — Joe Watkins — 2013-04-07T09:27:05+00:00

URL: https://externals.io/message/66973#66996 · In reply to: #66991

> Hi!
 >
 >
> > […]
 >
 > 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.
 >
> > […]
 >
 > 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 ...

---

## #66997 — Pierre Joye — 2013-04-07T11:10:14+00:00

URL: https://externals.io/message/66973#66997 · In reply to: #66996

hi,



>     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 ...

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