better docs for define 

closes #934