Documentation for H3 Directed Edge Index could be better.

[SkybuckFlying]

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.

[nrabinowitz]

Did you see https://h3geo.org/docs/core-library/h3Indexing ?
There's also an index bit layout explorer that might help: https://observablehq.com/@nrabinowitz/h3-index-bit-layout

[SkybuckFlying]

Yes, first link, looked at it like a million times by now, feels like it. Ultimately I got it... but the wording is a bit confusing for example:

"4 bits to indicate the H3 Unidirectional Edge index mode,"

While the bit layout does not show these words, I just shows "mode'.

So a better description would be something like:

"The 4 bit mode field is used to indicate the H3 Unidirectional Edge index mode,"

Another example:

"3 bits to indicate the edge (1-6) of the origin cell,"

A better description would be:

"The 3 bit Mode-Dependent field is used to store the edge (1-6) of the origin cell,"

Concerning link two, it does not follow the original layout as shown in link 1, so that feels a bit like a disconnect and it's not interactive, where the fields can be individually manipulated to see the effect, not that it would be of much use, maybe a little bit.

What is important is to show the different type of indexes and how they dependent on the mode field. However to explain the basic concept of H3 Index it's alright but that is kinda already done in the layout on link 1, which btw could also be a bit better, to me it seems kind upside down... and the left values could be placed on the right, or changed to make more sense.

Plus the hexadecimal is more confusing than it does any good, plus each row could be counted.

I will give you myself which is somewhat usefull how to quickly see the correct offset. I also find the bit layout on link 1 kinda confusing/misleading because it does not use multiple blocks to depict 3 bits, so for example it uses 1 box for 3 bits, instead of 3 boxes for 3 bits. The latter would be a bit more clear.
Plus using single or double letters inside of the boxes could make it more clear which bit exactly belongs to which field:
Plus legend is nice, being off even 1 bit can have nasty consequences so it's important to get every right/exact:

Example:

DX = D=Digit X=Number
B = Base Cell
R = Resolution
MD = Mode Dependent
M = Mode
. = Reserved

        63  62  61  60  59  58  57  56  55  54  53  52  51  50  49  48
0063    .   M   M   M   M   MD  MD  MD  R   R   R   R   B   B   B   B    0048

	47  46  45  44  43  42  41  40  39  38  37  36  35  34  33  32
0047    B   B   B   D1  D1  D1  D2  D2  D2  D3  D3  D3  D4  D4  D4  D5   0032

	31  30  29  28  27  26  25  24  23  22  21  20  19  18  17  16
0031    D5  D5  D6  D6  D6  D7  D7  D7  D8  D8  D8  D9  D9  D9  D10 D10  0016

        15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
0015    D10 D11 D11 D12 D12 D12 D13 D13 D13 D14 D14 D14 D14 D15 D15 D15  0000

(I have re-posted this under a new issue, because I think it is worth filing it under a better title description, to find it back in the future, in that posting I also have re-arranged the legend to match the table under it a bit better, and also gave a better description how the current table on link 1 has it's problems).

[SkybuckFlying]

My initial depiction for myself was this, but the above one is a bit nicer because it follows the link 1 picture better:

{

  Fields and bits and bit positions
  A = Digit 15 = 3 bits = 00..02 bit offset
  B = Digit 14 = 3 bits = 03..05 bit offset
  C = Digit 13 = 3 bits = 06..08 bit offset
  D = Digit 12 = 3 bits = 09..11 bit offset
  E = Digit 11 = 3 bits = 12..14 bit offset
  F = Digit 10 = 3 bits = 15..17 bit offset
  G = Digit 09 = 3 bits = 18..20 bit offset
  H = Digit 08 = 3 bits = 21..23 bit offset
  I = Digit 07 = 3 bits = 24..26 bit offset
  J = Digit 06 = 3 bits = 27..29 bit offset
  K = Digit 05 = 3 bits = 30..32 bit offset
  L = Digit 04 = 3 bits = 33..35 bit offset
  M = Digit 03 = 3 bits = 36..38 bit offset
  N = Digit 02 = 3 bits = 39..41 bit offset
  O = Digit 01 = 3 bits = 42..44 bit offset
  P = Base Cell = 7 bits = 45..51 bit offset
  Q = Resolution = 4 bits = 52..55 bit offset
  R = Mode-Dependent = 3 bits = 56..58 bit offset
  S = Mode = 4 bits = 59..62 bit offset
  T = Reserved = 1 bit = 63 bit offset

  bit positions
  0         1         2         3         4         5         6
  0123456789012345678901234567890123456789012345678901234567890123
  AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPPPPPQQQQRRRSSSST

}

[SkybuckFlying]

The first ascii art could even be improved, by numbering the letters depending on which bit it is, in case there is any doubt which bit is the high order and which bit is the low order, this might actually not be such a bad idea, in case code is ported to other machine that have a different bit endianness, there is also byte endianness to worry about.

However I think the picture is pretty clear, the order is clear, and the fields are small enough to count which bit position it is, so adding bit numbers to it would probably make more clutter than it's worth it, but it could still be considered.