Is Javadoc the right way to tell a user of a security issue? [closed]

Question

I'm trying to answer this question and I believe the Javadoc would solve the problem:

You have found that a method in one of your (otherwise excellent) classes has a security problem and you want to tell users that it is not a good idea to use the method anymore. How do you do this?

Answer 1

I would suggest to deprecate the method.

How and when to deprecate API

When you design an API, carefully consider whether it supersedes an old API. If it does, and you wish to encourage developers (users of the API) to migrate to the new API, then deprecate the old API. Valid reasons to deprecate an API include:

It is insecure, buggy, or highly inefficient

This will automatically get included in the Javadocs and will give a clear cut signal that this method should not be used.