Improve hook_schema_alter() documentation.

Ah, you are right. Apparently, I was not thinking clearly (somehow I was thinking of schema_alter()ing as an on-install task. But the hook is called whenever the schema information is rebuilt, so it likely needs to be in the .module file.

Leaving this open because:

1. Should we document that hook_schema_alter() needs to / should go into the .module file? I know this is the silent default, but given hook_schema_alter()s close connection to hook_schema() (which MUST be in the .install file), an additional note might not hurt?

2. The precise use and effect of hook_schema_alter() could be made clearer. The current version says:

When a module modifies the database structure of another module (by changing, adding or removing fields, keys or indexes), it should implement hook_schema_alter() to update the default $schema to take its changes into account.

Implicit in this is that just implementing hook_schema_alter() will NOT change the database (at least for already-installed modules). Maybe we should make this explicit?

In general, it is a little unclear (to me) how one would use hook_schema_alter() in conjunction with hook_(un)install(): I.e. how is the following scenario to be handled:

Module A alter()s module B's schema and, in A_install(), it makes the corresponding changes to the database.

Now suppose that A is installed before B. A's schema_alter() will be available and called when schema information is collected. However, since A's hook_install() was called before B even was there, the database will go unaltered. This would mean that the schema information and the database are out of sync, right?

Perhaps the intention is that a module should only schema_alter() parts of the schema of modules it depends on (i.e. in the above example, A should depend on B, preventing the scenario from happening). If so, this should be documented.

Well, I was not suggest to provide a full explanation of this use case (or a tutorial for using this function), but rather I was tryting to illustrate how I don't quite understand what the hook does / is supposed to do after reading the current doc. Minimally if this

presumably if module B is altering module A's schema, module B would have module A as a dependency, so you would never be able to have module B enabled/installed without module A also being enabled, right?

is actually an assumption that drupal makes, it should be documented in the API doc (and this is not obvious---think about module A that providing optional integration with B if it is present, then you would not have a dependency, but A might still do something to B's schema (though perhaps it should not).