add annotations for many more functions, and a few comments where we
should be able to say something interesting