somewhat more docs, better error message