diff --git a/java/java-analysis-impl/src/com/intellij/codeInspection/dataFlow/Mutability.java b/java/java-analysis-impl/src/com/intellij/codeInspection/dataFlow/Mutability.java
index f1bacecb0c4e..ce85819983b0 100644
--- a/java/java-analysis-impl/src/com/intellij/codeInspection/dataFlow/Mutability.java
+++ b/java/java-analysis-impl/src/com/intellij/codeInspection/dataFlow/Mutability.java
@@ -13,7 +13,25 @@ import org.jetbrains.annotations.NotNull;
 import java.util.Collections;
 
 public enum Mutability {
-  UNKNOWN, MUTABLE, UNMODIFIABLE, UNMODIFIABLE_VIEW;
+  /**
+   * Mutability is not known; probably value can be mutated
+   */
+  UNKNOWN,
+  /**
+   * A value is known to be mutable (e.g. elements are sometimes added to the collection)
+   */
+  MUTABLE,
+  /**
+   * A value is known to be immutable. For collection no elements could be added, removed or altered (though if collection
+   * contains mutable elements, they still could be mutated).
+   */
+  UNMODIFIABLE,
+  /**
+   * A value is known to be an immutable view over a possibly mutable value: it cannot be mutated directly using this
+   * reference; however subsequent reads (e.g. {@link java.util.Collection#size}) may return different results if the
+   * underlying value is mutated by somebody else.
+   */
+  UNMODIFIABLE_VIEW;
 
   public static final String UNMODIFIABLE_ANNOTATION = "org.jetbrains.annotations.Unmodifiable";
   public static final String UNMODIFIABLE_VIEW_ANNOTATION = "org.jetbrains.annotations.UnmodifiableView";
@@ -22,6 +40,15 @@ public enum Mutability {
     return this == UNMODIFIABLE || this == UNMODIFIABLE_VIEW;
   }
 
+  /**
+   * Returns a mutability of the supplied element, if known. The element could be a method
+   * (in this case the return value mutability is returned), a method parameter
+   * (the returned mutability will reflect whether the method can mutate the parameter),
+   * or a field (in this case the mutability could be obtained from its initializer).
+   *
+   * @param owner an element to check the mutability
+   * @return a Mutability enum value; {@link #UNKNOWN} if cannot be determined or specified element type is not supported.
+   */
   @NotNull
   public static Mutability getMutability(@NotNull PsiModifierListOwner owner) {
     if (owner instanceof PsiParameter && owner.getParent() instanceof PsiParameterList) {