Location Dependency docs are unclear

[waywardmonkeys]

I think a couple of things should be made more clear in the docs on location dependencies:

• That the same arena must be passed in to each call for the mps_ld_t.
• That the mps_ld_t doesn't just store the arena pointer for itself to keep the size down since this is something that might be stored in every single hash table.
• Some discussion perhaps of how it works.
• A table of contents or something near the top of the page would help to give a overview that there are 3 important sections for reset, add, test ... right now, each part is long enough that it needs something to make it more approachable with an overview and then detail.

Also, in the code snippet that does this:

        b = table_rehash(tbl, tbl->table.buckets->buckets.length, key);

there's a comment in the text afterwards about how it returns b ... but a comment in the actual code block would make this more clear:

        /* Since we're iterating over the buckets, return the matching bucket here now. See below for detailed explanation. */
        b = table_rehash(tbl, tbl->table.buckets->buckets.length, key);

Or that could be something where you use the code block feature to call out particular line numbers... I'm not sure what would be best.

[rptb1]

This issue arose from a Keybase conversation keybase://chat/rptb1,bmitchener/1029 between @rptb1 and @waywardmonkeys that contains some suggestions for design documents too:

1. LDs are per-arena because zone shifts and epochs are per arena.
2. The LD structure is intended to be tiny, so that clients can cheaply embed it in their structures, and so we rely on the client program to pass the arena. There's potential for error on the part of the client program with multiple arenas.
3. The design documentation for LDs is in the leader comment of ld.c and git blame reveals this is my doing in 1996. Time for a design document.

[rptb1]

The manual section on Location Dependency uses the phrase "the toy Scheme interpreter" several times, and quotes code examples from it, but does not link to it. We should fix that while we're fixing other things here.

[thejayps]

JPH + RB: Essential to make unclear documentation clear