Home » Database » MDB2 » Bug #8670

[2006-09-10 15:30 UTC] jo at durchholz dot org

Description:
------------
Many functions document their result as:

* Return: data array on success, a MDB2 error on failure

This is largely useless, because it doesn't tell me what's in the array indexes and what in the values. I have to spend hours to recover this kind of information from the source, and the results are unreliable becaus I may make mistakes, because a driver that I have not installed may behave differently, or because I may have taken a bug for a feature.

Here are proposed templates for documenting result values:

E.g. for listTableIndexes($table):
* Return: array|MDB2::Error An array of index names on success

E.g. for getTableIndexDefinition($table, $index_name):
* Return: array|MDB2::Error An associative array with information on the index:
'fields' => Array, one entry per field in the index.
$field_name => A (possibly empty) array with information on the field in the index.
'sorting' => Sort order for that field in this index. (Not available for all database engine or all kinds of index.)

[2006-12-05 17:16 UTC] jo at durchholz dot org

The functions in MDB_Driver_Reverse_Common are still problematic.
Compared with other functions, they suffer from more and more relevant incompatibilities, which makes documenting them both more difficult and more important.

[2006-12-06 08:59 UTC] jo at durchholz dot org

I'm not 100% sure what the incompatibilities were.
I recall dimly that I found a comment in driver code that mentioned in passing that there were incompatibilities; I haven't encountered any from firsthand experience though, since my usual workflow is to look up the docs, then stay away from areas of incompatibility.

I'm unable to look at the docs right now, "Browse the source tree" is taking ages for some reason.
Let me know if you wish me to take another look.

(BTW that's an impressively short bug list that MDB2 has now. Thanks!)