Documentation for H3 Directed Edge Index could be better.

I had a hard time figuring out where the bits go.

After studieing the C source code and it's macros and it's bitset offsets and it's masks I came to the conclusion that:

"3 bits to indicate the edge (1-6) of the origin cell" are mapped to "Mode-Dependent" as depicted later down at

"Bit layout of H3Index".

The source code however calls these "reserved bits" not to be confused with the "reserved bit".

Perhaps source code could be modified so it renames to "mode-dependent".

So all mode 2 for a H3Index seems to do is write 1 to 6 to the mode-dependent 3 bits to indicate some kind of edge.

I am still trying to understand how edges and mode 2 work. The documentation could also be better in this regards/expanded/extended to example how these additional 3 bits or how mode 2 is used in code.

But the most important thing is for implementators/users/bindings to be able to understand how to setup an H3Index correctly.

The next part also isn't terribly clear:

"Subsequent bits matching the index bits of the origin cell."

This is knowledge from the source code, it indeed copies these bits from the origin cell, but this is completely obviously to the end user because the end user doesn't even know how it all works and why it does this.

What is far more important is how the bits are used.

Basically they are used to same way as mode 1.

Again 0 to 15 cell indexes.

Perhaps it's best to make a bit layout per mode, so it's perfectly clear how each mode is used. Just a textual description could be interpreted in all kinds of ways without knowing for sure...

Except if the user strictly follows the order, from highest 64 bit to lower bits...

The old saying, "a picture describes a 1000 words" might apply here ! ;)

The risk is that less experienced programmers will interpret the documentation/description/lines of explanation out of order and reinterpret them in their own way. For example mapping 3 bits to the wrong bits because of miss-understanding.

There is further room for confusion, because of the 1st reversed bit and the other 3 reserved bits which are actually depicted as mode-dependent bits.

Only studieing the source code clearifies this. Hopefully the documentation can be improved to make it more clear.

Start with the existing “Bit layout of H3Index” documentation and the C source macros, bitset offsets, and masks referenced in the issue. Compare the mode 2 layout with mode 1 and document how the mode-dependent bits and origin-cell index bits are used, ideally with a per-mode diagram or example. Done means implementers can construct and interpret an H3Index without reverse-engineering the source.