add deprecation notice to docs

it only shows up in the code.