resync docs with YARD docstrings
add better warning to prevent direct editing of auto-gen docs