1 files changed, 9 insertions, 0 deletions
diff --git a/python/src/com/jetbrains/python/refactoring/PyReplaceExpressionUtil.java b/python/src/com/jetbrains/python/refactoring/PyReplaceExpressionUtil.java
index f4cb9e6a73f3..2cebb3ec2720 100644
--- a/python/src/com/jetbrains/python/refactoring/PyReplaceExpressionUtil.java
+++ b/python/src/com/jetbrains/python/refactoring/PyReplaceExpressionUtil.java
@@ -47,6 +47,15 @@ import static com.jetbrains.python.inspections.PyStringFormatParser.parsePercent
  * @author Dennis.Ushakov
  */
 public class PyReplaceExpressionUtil implements PyElementTypes {
+  /**
+   * This marker is added in cases where valid selection nevertheless breaks existing expression.
+   * It can happen in cases like (here {@code <start> and <end>} represent selection boundaries):
+   * <ul>
+   *   <li>Selection conflicts with operator precedence: {@code n = 1 * <start>2 + 3<end>}</li>
+   *   <li>Selection conflicts with operator associativity: {@code n = 1 + <start>2 + 3<end>}</li>
+   *   <li>Part of string literal is selected: {@code s = 'green <start>eggs<end> and ham'}</li>
+   * </ul>
+   */
   public static final Key<Pair<PsiElement, TextRange>> SELECTION_BREAKS_AST_NODE =
     new Key<Pair<PsiElement, TextRange>>("python.selection.breaks.ast.node");