Re: what is going on with gtk.php.net?

I'm moving this discussion over to php-gtk-doc... James Cameron wrote:

a) the GTK+ documentation is very good, and that is *mainly* all that is needed, along with a bit of glue documentation that explains *how* to translate GTK+ concepts into PHP-GTK concepts. If the GTK+ documentation is insufficient, then *it* should be improved before improving PHP-GTK documentation.

I think I understand your reasoning here, but it's already been mentioned that even the GTK+ documentation is incomplete. If we merely use the PHP-GTK manual to explain how to read the GTK+ manual and translate those concepts into PHP-GTK concepts, then we have only helped our readers insomuch as the GTK+ docs are worth--and they're not worth much if they're incomplete. I think we could have a section of PHP-GTK documentation that points site users to the GTK+ docs and helps them understand the relationship, but the rest of the docs should be a reference to the PHP-GTK functions and classes.

b) documentation always lags code, because there's little benefit to creating documentation, compared to the benefit of creating code, and by far I'd rather have code that is undocumented than no code at all. I can use the former, but not the latter.

I completely disagree. I, along with others here, constantly have the manual at php.net open as we develop. When we need to reference a function/class, we look it up. I don't go sifting through lines and lines of code to find a function and figure out how it works; I rely on the excellent reference that the php.net manual provides--even if it doesn't provide tons of coding examples (we can leave that to the user-supplied notes).

c) documentation and code together are redundant, we have the sources, so when there's anything strange about how PHP-GTK works, I just lift the hood and start poking around. Sometimes my poking leads me into GTK+ code as well. (Yes, I know; many of you don't poke into C code).

I also disagree here. I don't think documentation and code are redundant when together. I think that one provides support for the other. The code supports the documentation, and the documentation supports the code. It's a perfect marriage, and I think that the php.net manual provides excellent examples of how this works well. IMO, I haven't seen a better on-line manual for a programming language. Perhaps I've misunderstood what you're saying, but it seems to me that you're saying that the reference material provided by any manual is unnecessary, and what you think benefits others the best is just straight code with no documentation. That is what I disagree with. -- Regards, Ben Ramsey http://benramsey.com --------------------------------------------------- http://www.phpcommunity.org/ Open Source, Open Community Visit for more information or to join the movement. ---------------------------------------------------