I've pushed some documentation in both customizing.txt and in hyperdb.filter (almost the same wording). I notice that we have almost no documentation on the hyperdb-level API (There is some documentation of the HTML wrapper but not on the underlying hyperdb API)