Fixes per menn0 review.

godoc and other comment rewording/improvements.
Use errors.New for Errorf's without format args.
Better variable names for caveat calculation & parsing.