[libcxx-commits] [libcxx] [libc++] Document how __tree is layed out and how we iterate through it (PR #152453)

[Louis Dionne via libcxx-commits]

================
@@ -49,6 +49,27 @@
 _LIBCPP_PUSH_MACROS
 #include <__undef_macros>
 
+// __tree is a red-black-tree implementation used for the associative containers (i.e. (multi)map/set). To allow for
+// constant time lookup, it stores
+// - (1) a pointer to the node with the smallest (i.e. leftmost) element, namely __begin_node_
+// - (2) the number of nodes in the tree, namely __size_
+//
+// A pointer to the root of the tree is stored in the __end_node_.
+// A tree looks like this in memory:
+//
+//      __end_node_
+//           |
+//          root
+//         /    \
+//       l1       r1
+//      /  \     /  \
+//    ...  ... ...  ...
+//
+// All nodes except __end_node_ have a __left_ and __right_ pointer as well as a __parent_ pointer.
+// __end_node_ only contains a __left_ pointer, which point to the root of the tree.
----------------
ldionne wrote:

```suggestion
// __end_node_ only contains a __left_ pointer, which points to the root of the tree.
```

https://github.com/llvm/llvm-project/pull/152453