Indicates that the annotated method should not be called under any normal circumstances, yet is either impossible to remove, or should not ever be removed. Example:

public class ImmutableList<E> implements List<E> {
  @DoNotCall("guaranteed to throw an exception")
  @Override public add(E e) {
    throw new UnsupportedOperationException();
  }
}

By the demands of the List interface, this method can never be removed. However, since it should always throw an exception, there can be no valid reason to call it except in the rarest of circumstances. Although this information can only benefit users who have a reference of type ImmutableList (not List), it's a good start.

If the typical caller's best remedy is to "inline" the method, InlineMe is probably a better option; read there for more information. Using both annotations together is probably unnecessary.

Note on testing: A @DoNotCall method should still have unit tests.

@DoNotCall and deprecation

Deprecation may feel inappropriate or misleading in cases where there is no intention to ever remove the method. It might create the impression of a "blemish" on your API; something that should be fixed. Moreover, it's generally hard to enforce deprecation warnings as strongly as a @DoNotCall violation should be.

But, when choosing the @DoNotCall option, consider adding Deprecated as well anyway, so that any tools that don't support @DoNotCall can still do something reasonable to discourage usage. This practice does have some cost; for example, suppression would require @SuppressWarnings({"DoNotCall", "deprecation"}).

Tool support

Error Prone supports this annotation via its DoNotCall pattern.