In general, it's probably a bad idea for doc comments to include explicit references (e.g., @see tags) to deprecated elements (classes, interfaces, exceptions, members, etc.). It would be help if javadoc would issue a warning message for any such references that it encounters.