More examples, illustrate the range of options and document all special cases. Think from perspective of "what context is this used from?" instead of just list

More examples, illustrate the range of options and document all special cases. Think from perspective of "what context is this used from?" instead of just listing possibilities. Try to document what is going behind the scenes as much as possible, with minimal local jargon. Making stuff accessible to wider audience for debugging/auditing requires explaining design decisions at high-level(interface) and low-level(what is actually used). Otherwise users will start treating it as black-box binary blobs of mystery "code" that works by magic, because people just don't read source code.