At a general level, abstraction is very powerful, but it has an
inherent serious risk that there is no Rosetta stone around to
explain how it works (or a Martin or a Bart). As someone who comes
to the open source world from a non-Unix (I pre-date it!), rarely
use C background, I spend a lot of time trying to figure out such
cryptic but important symbolism. I also suspect a large portion of
the "bugs" that arise come from small but critical breakages in
the pointer chains.
This isn't recommending wholesale changes, but urging more and
clearer documentation. As someone who struggles to provide enough
documentation, I know that is a big demand. But I also know that every
time I forget or am lazy, I'm usually both the perpetrator and the
eventual victim
of not documenting clearly.
JN