Как Java doc является инвариантом для класса?

Question

Я хочу знать, где именно должен идти комментарий, и какое ключевое слово я должен использовать, поскольку я действительно не могу найти пример в Интернете, должен ли я, например, сделать это?

/** 
* @invariant invariant example 
*/ 
public class Example { 
} 

Answer 1

Есть несколько possibilites

@Contract аннотаций

Некоторые примеры

• @Contract ("_, нуль -> нулевой") - метод возвращает нуль если его второй аргумент имеет значение null.

• @Contract ("_, нуль -> нуль;! _, Нуль -> нуль") - метод возвращает нулевое значение, если ее второй аргумент имеет нулевое значение, а не-нуль иначе.

• @Contract ("true -> fail") - типичный метод assertFalse() , который выдает исключение, если ему передается значение true.

См https://www.jetbrains.com/help/idea/2016.2/contract-annotations.html для более подробной информации.

Вы можете использовать их без IntelliJ IDEA. ИДЕЯ просто умеет поддерживать эти аннотации. Он проверит ваш код метода, если определенные инварианты действительно выполнены.

Текстовое описание

Этот метод не распространяется на все случаи. Для более сложных зависимостей между полями вам нужно описать инвариант, используя английские слова.

Например, https://docs.oracle.com/javase/7/docs/api/java/util/Map.html#put(K,%20V)

Если карта, ранее содержавшиеся отображения для ключа, старое значение заменяется указанным значением.

Исключения

Кроме того, исключения могут быть использованы для описания и обеспечения инвариантно.Для вышеупомянутого Map.put метода мы имеем следующие исключения для недопустимых аргументов (аргументы, которые нарушают инвариант класса)

• @throws UnsupportedOperationException если операция положить не поддерживается на этой карте
  • @throws ClassCastException, если класс указанного ключа или значение предотвращает его сохранение на этой карте
  • @throws NullPointerException, если указанный ключ или значение равно нулю и эта карта не допускает нулевые ключей или значений
  • @throws IllegalArgumentException, если какое-то свойство указанного ключа или значения не мешает ему быть сохранены в этой карте