The function names in Monocypher do not clearly differentiate between low-level primitives that probably shouldn't be used directly, and high-level constructions meant for users.
The naming convention will not be fixed. Unfortunately, a choice has to be made between making function names as safe as possible, and backwards compatibility. Backwards compatibility wins.
Some measures however can still be taken.
The manual on the web site already displays a hierarchic structure that hides the advanced constructions somewhat. Something similar should be done for the generated html pages that ship with the tarball.
The monocypher.h header fails to put some advanced functions in the "expert only" section. The offending prototypes should be moved down there.
The monocypher.h header should include suitably stern warnings for every advanced functions, to maximise the chances that users would notice them if they grab it from there instead of reading the documentation.
I acknowledge that this won't be enough for everyone. Some users will manage to grab the prototype of advanced functions without reading the documentation and without noticing the (upcoming) warnings in the header. Sorry about them.
The function names in Monocypher do not clearly differentiate between low-level primitives that probably shouldn't be used directly, and high-level constructions meant for users.
The naming convention will not be fixed. Unfortunately, a choice has to be made between making function names as safe as possible, and backwards compatibility. Backwards compatibility wins.
Some measures however can still be taken.
monocypher.hheader fails to put some advanced functions in the "expert only" section. The offending prototypes should be moved down there.monocypher.hheader should include suitably stern warnings for every advanced functions, to maximise the chances that users would notice them if they grab it from there instead of reading the documentation.I acknowledge that this won't be enough for everyone. Some users will manage to grab the prototype of advanced functions without reading the documentation and without noticing the (upcoming) warnings in the header. Sorry about them.