How to document database usage with PHPdoc?

Question

Now I am wondering if others document database usage in function headers ... for instance, a fn() might read or write a database (or table thereof), or create, modify or drop a database or table. (side question: should a fn() which changes the database with "USE xxx" 'remember' the current database on entry and USE it again before exit?)

It seems to me that this sort of thing should be documented, but how best to do so? @uses, or what?

Answer 1

Why not use @link and a list, along with list of helpers:

/**
 * Some comments here.
 *
 * Helper functions:
 * * {@link someHelper}
 * * {@link theOtherHelper}
 *
 * Reads tables:
 * * {@link Table1}
 * * {@link Table2}
 *
 * Reads/Writes tables:
 * * {@link Table3}
 * * {@link Table4}
 */

Then you make some topic pages for those tables, with nothing but a short description, "Holds parameters for business process X."