Improve inline documentation for behaviors

fixes #1091