fix broken specs and add some documentation