DBTNG docs need review

[Larry Garfield]

Hello, documentation type people. :-)

Some time ago I wrote up documentation on the new DBTNG system. It was good,
save for conditional handling which was missing for a while because it was
much harder to explain. That is now written. And there was much rejoicing.

I would therefore like to get feedback from the Docs folks on the
documentation, particularly on the conditionals as that's the hardest part to
grok.

http://drupal.org/dbtng-documentation

Comments on the pages, replies to this email, or direct edits for small things
are all cool by me. :-) I know driver documentation is still missing. That's
because that API is still subject to change, so it's not worth documenting
until we're done breaking it.

Thanks all!

[Rob Loach]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Larry,

Nicely done on the documentation. Everything is easy to read, and well
organized. Great job!

One thing to note is that hook.api.php files made it into core
(http://drupal.org/node/314870), so are there any places with the new
database layer that would benefit from having any extra database.api.php
documentation files around?

Thanks a lot,

- --
Rob Loach
http://www.robloach.net

Post by Larry Garfield
Hello, documentation type people. :-)
Some time ago I wrote up documentation on the new DBTNG system. It was good,
save for conditional handling which was missing for a while because it was
much harder to explain. That is now written. And there was much rejoicing.
I would therefore like to get feedback from the Docs folks on the
documentation, particularly on the conditionals as that's the hardest part to
grok.
http://drupal.org/dbtng-documentation
Comments on the pages, replies to this email, or direct edits for small things
are all cool by me. :-) I know driver documentation is still missing. That's
because that API is still subject to change, so it's not worth documenting
until we're done breaking it.
Thanks all!

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFJSTCkYn9qH3fN54QRAp8CAKCnHpjiO+bGB+m0sc7GFkMXSZc5TACfRdWj
lex4xlzqf6wkHYULSGjZLEU=
=xK2h
-----END PGP SIGNATURE-----
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Larry Garfield]

Post by Rob Loach
Hi Larry,
Nicely done on the documentation. Everything is easy to read, and well
organized. Great job!
One thing to note is that hook.api.php files made it into core
(http://drupal.org/node/314870), so are there any places with the new
database layer that would benefit from having any extra database.api.php
documentation files around?
Thanks a lot,

Hey neat, that made it in.

I think DBTNG introduces only one hook, hook_query_alter, so I've opened an
issue for that:

http://drupal.org/node/348519

I'm not sure that in-code is the best place to document the rest of DBTNG,
beyond the docblocks already in database.inc. The handbooks are probably
better as it's less API samples and more prose explanations. That said, I'm
fine if someone wants to copy portions of the handbooks into a docblock.
(Technically the licenses are incompatible, but as the original author of 98%
of the DBTNG documentation I hereby dual-license it as needed yadda yadda.)

[Nathaniel Catchpole]

Just saw the docs here have been updated -
http://api.drupal.org/api/group/database/7 - this could do with a link to
the handbook section too though probably.

Nat

Post by Larry Garfield

Post by Rob Loach
Hi Larry,
Nicely done on the documentation. Everything is easy to read, and well
organized. Great job!
One thing to note is that hook.api.php files made it into core
(http://drupal.org/node/314870), so are there any places with the new
database layer that would benefit from having any extra database.api.php
documentation files around?
Thanks a lot,

Hey neat, that made it in.
I think DBTNG introduces only one hook, hook_query_alter, so I've opened an
http://drupal.org/node/348519
I'm not sure that in-code is the best place to document the rest of DBTNG,
beyond the docblocks already in database.inc. The handbooks are probably
better as it's less API samples and more prose explanations. That said, I'm
fine if someone wants to copy portions of the handbooks into a docblock.
(Technically the licenses are incompatible, but as the original author of 98%
of the DBTNG documentation I hereby dual-license it as needed yadda yadda.)
--
Larry Garfield
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Larry Garfield]

Changed the link on the first page of the docs to point to the database group directly. API.module still needs to be taught how to handle classes, though.

--Larry Garfield

Post by Nathaniel Catchpole
Just saw the docs here have been updated -
http://api.drupal.org/api/group/database/7 - this could do with a link to
the handbook section too though probably.
Nat
On Thu, Dec 18, 2008 at 4:28 AM, Larry Garfield

Post by Larry Garfield

Post by Rob Loach
Hi Larry,
Nicely done on the documentation. Everything is easy to read, and well
organized. Great job!
One thing to note is that hook.api.php files made it into core
(http://drupal.org/node/314870), so are there any places with the new
database layer that would benefit from having any extra

database.api.php

Post by Larry Garfield

Post by Rob Loach
documentation files around?
Thanks a lot,

Hey neat, that made it in.
I think DBTNG introduces only one hook, hook_query_alter, so I've opened

an

Post by Larry Garfield
http://drupal.org/node/348519
I'm not sure that in-code is the best place to document the rest of

DBTNG,

Post by Larry Garfield
beyond the docblocks already in database.inc. The handbooks are

probably

Post by Larry Garfield
better as it's less API samples and more prose explanations. That said, I'm
fine if someone wants to copy portions of the handbooks into a docblock.
(Technically the licenses are incompatible, but as the original author

of

Post by Larry Garfield
98%
of the DBTNG documentation I hereby dual-license it as needed yadda

yadda.)

Post by Larry Garfield
--
Larry Garfield
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Neil Drumm]

Yes, that is high on the list. We need to chunk the code into
functions/constants/etc with PHP's tokenizer instead of regular
expressions hard-coded to our coding conventions.
http://drupal.org/node/300031

-Neil

Post by Larry Garfield
Changed the link on the first page of the docs to point to the database group directly. API.module still needs to be taught how to handle classes, though.
--Larry Garfield

Post by Nathaniel Catchpole
Just saw the docs here have been updated -
http://api.drupal.org/api/group/database/7 - this could do with a link to
the handbook section too though probably.
Nat
On Thu, Dec 18, 2008 at 4:28 AM, Larry Garfield

Post by Larry Garfield

Post by Rob Loach
Hi Larry,
Nicely done on the documentation. Everything is easy to read, and well
organized. Great job!
One thing to note is that hook.api.php files made it into core
(http://drupal.org/node/314870), so are there any places with the new
database layer that would benefit from having any extra

database.api.php

Post by Larry Garfield

Post by Rob Loach
documentation files around?
Thanks a lot,

Hey neat, that made it in.
I think DBTNG introduces only one hook, hook_query_alter, so I've opened

an

Post by Larry Garfield
http://drupal.org/node/348519
I'm not sure that in-code is the best place to document the rest of

DBTNG,

Post by Larry Garfield
beyond the docblocks already in database.inc. The handbooks are

probably

Post by Larry Garfield
better as it's less API samples and more prose explanations. That said, I'm
fine if someone wants to copy portions of the handbooks into a docblock.
(Technically the licenses are incompatible, but as the original author

of

Post by Larry Garfield
98%
of the DBTNG documentation I hereby dual-license it as needed yadda

yadda.)

Post by Larry Garfield
--
Larry Garfield
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/