On Monday 07 March 2005 20:32, Warren Young wrote:
| Steve Mansfield wrote:
| > Indeed - as I go through the manual (which, on reflection, is really,
| > *really* awful) I'm having a lot of those 'huh?' moments. Trouble is, at
| > this stage I don't know whether those are caused by my lack of knowledge
| > about C++ or just obscurity in the manual itself.
| The problem isn't that the manual is obscure, it's that it's a reference
| manual, not a tutorial. Sure, there's stuff in there that tries to be a
| tutorial, but they should be separated out and clarified. We should
| either have two manuals, or at least a manual in two sections. What a
| newbie wants from a manual is not the same thing that those of us who
| have been using MySQL++ for years want.
True, up to a point. The two problems with the manual (from a newbie
* It tries to inform by inference - in other words, it relies too heavily on
showing a code example (which, of course, now differs wildly from the
examples actually supplied) and then expecting one to devine what's going on
* It's maddeningly random and partial in what it tells you.
Okay, an example or two:
I look at the early section on Result Sets where it attempts to describe the
different types, but with no indication on how they differ in practical terms
(ie, some idea of why you'd use one rather than the other) or what form these
results sets take.
More specifically, the 'simple' example shows how to pull some rows from a
table and print them. I managed to get this working without too much trouble,
but then I look at the query object and see that it has a number of methods -
query.store(), query.preview() and I immediately want to know what other
methods there are, what types they return, what parameters, if any, they
might take. In other words, a reference list of all the methods, properties,
structures & types in the API would be very interesting. That way I can play
around with them and learn by experience.
Now, you might argue that much of this info can be gleaned by sifting through
the code, looking at function and class declarations etc. But that's the kind
of effort a manual is meant to avoid.
I find the PHP manual very useful partly because I can browse it - I've
discovered all manner of useful functions that I wouldn't have thought to
search for that way. It tells you what each function does, what params it
takes, what type it returns.
I guess what I'm saying is that I need Chapter 5! And obviously the manual
needs to be brought up to date by using the actual code from the examples.
Lots of commenting in the code might help, too.
Anyway, I'll see if I can come up with some sensible comments on the manual