[wp-docs] [Dev Doc] WordPress Database Reference

[Owen Winkler]

Michael D.Adams wrote:
> I've got a rough sketch of the wpdb class at 
> http://codex.wordpress.org/User:MDAWaffe/Functions .  I agree now that 
> the content is better served from the [[WordPress Function Reference]] 
> section.

This page looks fairly complete.  My only thought (and don't take this 
as a negative, since I may still come around to this idea) is that I 
find the functional function references a bit unnerving.  (Functional 
function references = Titling a function by what it does rather than 
using its name.)

What I imagine might be optimal from an end-user/developer point of view 
is an actual "reference" with just the function definitions and 
parameters, and then a how-to for each section that links to the reference.

I'm rambling here because there's an alarm going off in my intuition. 
Is it a false alarm?

> The sections delineated there were completely off the cuff.  Please 
> organize things differently if you see a better alternative.  In 
> particular, what do people think about each class (or natural group of 
> classes) getting its own box on the page? Also, I don't really know what 
> "basic functions" could be; functions from functions.php will probably 
> go into several categories.  Again, edit at will.  Owen, you seem to 
> have a good idea how things should be organized.  Do you mind poking the 
> page or listing a sectional hierarchy here?

Using the core filenames seems like a logical way to break up the larger 
sections, but I wonder if there are subsection groupings that make 
sense.  Like in my last message on this topic, I was talking about 
Options functions.  This grouping isn't large enoguh (the three 
functions currently in [[Writing a Plugin]]) for it's own major heading, 
but where does it go?  In which of these sections would you look for it?

I require more thought on this yet.  Maybe I just need to break it out 
and do it to see what it looks like.

> This brings up the subpage issue.  It seems the best way to implement to 
> me, but I'm open.  I suppose, then, each of the functions I describe for 
> the wpdb class should have its own page, with an umbrella page 
> describing database interface in general, the class variables, and the 
> class as a whole.

I think maybe that's what I was trying to say at the beginning - I would 
put the class reference on one page, and then have the description of 
the interface along with a few examples on another.  I don't know if I 
would put each function on its own page, though - that would seem to 
spawn a lot of clicking around.

For example, there could be a developer reference page, [[Accessing the 
Database]] that describes the interface and how to use it in general 
which has support function reference on [[wpdb Database Class]] (or 
whatever you want to call your current [[User:MDAWaffe/Functions]]). 
Perhaps the function reference could be embedded in the developer 
reference page, or maybe a simple link would suffice.

Similarly, I'd rip out the "#Saving Plugin Data to the Database" section 
from [[Writing a Plugin]], replace it with concrete examples that link 
to the ripped out stuff as a pure function reference.

I'm just looking at this from my perspective versus newbie devs.  For 
me, I want to skip the "How-to" page and just get the function 
parameters or whatever.  I don't want a lot of prosy stuff in the way of 
what I want to know, yet that stuff may be more important for others 
than the function reference itself.

Owen