improve docs and definitions