I started by reading the NaCl source and all the introductory material available—the web site, the two NaCl papers ("Cryptography in NaCl", "The security impact of a new cryptography library"), and quickly reviewed a couple of other papers (e.g. to understand deterministic encryption and D-H key exchange). I think the biggest problem I had was to understand nonce generation and handling properly. The "Cryptography …" paper does contain some advice that I ultimately implemented. But I had to think very hard about what it said before I was confident that I was doing what it said. For example, it says:
«…the nonce can be chosen as a simple counter: 0 for Alice’s first packet, 1 for Bob’s first packet, 2 for Alice’s second packet, 3 for Bob’s second packet, 4 for Alice’s third packet, 5 for Bob’s third packet, etc. Choosing the nonce as a counter followed by (e.g.) 32 random bits helps protect some protocols against denial-of-service attacks. In many applications it is better to increase the counter to, e.g., the number of nanoseconds that have passed since a standard epoch in the local clock, so that the current value of the counter does not leak the traffic rate.»
I managed to figure it out, but I would certainly have welcomed a more detailed explanation, and would have been very happy to have help from the code to do the right thing.
In contrast, the cryptography functions were easy enough to figure out and use (with the C API). The only mistake I kept making was specifying the secret key first and the public key second in all my function calls. Once I got used to doing it the other way around, it was fine. Zero-padding the messages was slightly ugly, but I didn't develop any especially strong feelings about it. (Aside: I actually ended up using TweetNaCl, but of course all the documentation is the same.)
I'm very pleased with the resulting code, anyway.
P.S. I looked at libsodium, but greatly preferred the unadorned library.