On Wed, Feb 4, 2015 at 7:13 PM, Howard Chu <hyc@symas.com> wrote:

The behavior wasn't settled, in the beginning. But you can read the mtest source code to see what the expected behavior is.

In an open source project, you are expected to read source code to understand what's going on.

I have been. 

Though, in this particular case, I needed to dig all the way down to LMDB page layout to grok key indexes, compare to mdb_cursor_next, search for instances of C_DEL, etc. to understand what was happening.

Reading code works better when we have something more modular and compositional, i.e. such that you can read and understand in small pieces. LMDB is just one big module, you can't understand most pieces without seeing the whole picture. This isn't a bad thing for its purpose, but it does mean good API documentation saves hours or days of reading code for someone who wants to just use LMDB.

Things have settled down enough now to formally document it though.

Then make it so. It will save a lot of people a lot of time. :)