Schema API page and hook_schema() doc need reorganization

The Schema API is more fully documented in this section of the Handbook:
http://drupal.org/node/146843

The documentation for hook_schema() points to this page, but the Schema API page does not currently:
http://api.drupal.org/api/drupal/includes--database.inc/group/schemaapi/6
I think it should.

I also think that the documentation that is on that page probably belongs in hook_schema() and not on this page, since it is mostly about the return values of hook_schema().
http://api.drupal.org/api/drupal/developer--hooks--install.php/function/...

This is still true in Drupal 7, and should be fixed there first and then ported back to Drupal 6:
http://api.drupal.org/api/drupal/includes--database--schema.inc/group/sc...
http://api.drupal.org/api/drupal/modules--system--system.api.php/functio...

Here's a patch. It moves the documentation about the schema structure from the Schema API page to hook_schema() [and cleans it up a bit], and makes sure that both hook_schema() and the Schema API page tell you where to get more information.

  * @defgroup schemaapi Schema API
  * @{
  *
- * A Drupal schema definition is an array structure representing one or
- * more tables and their related keys and indexes. A schema is defined by
- * hook_schema(), which usually lives in a modulename.install file.
+ * A Drupal schema definition is an array structure representing one or more
+ * tables and their related keys and indexes. A schema is defined in an
+ * implementation of hook_schema(), which is usually put into the
+ * modulename.install file. For more information on the structure of the
+ * schema definition, see the hook_schema() documentation, and the
+ * @link http://drupal.org/node/146843 Schema API handbook @endlink

I don't think any of this makes sense here. The group page should describe what the Schema API is about (ie. managing the database structure).

This doesn't say that the Schema API is about managing the database structure?

"A Drupal schema definition is an array structure representing one or more tables and their related keys and indexes."

What would you suggest instead?

updating, will click retest in a sec...

#2: 986546.patch queued for re-testing.

Looks like this needs a re-roll, and maybe an update to address comment #3 above, although I think the existing wording (the patch doesn't change the existing wording, just adds to it) is fine...

This is a very old issue and the docs are a lot better now. Closing.