half way through documenting core functions