more and more jsdocs; also throw for some manually curried fns