better docs and smarter parsing