[inlays] get back removed docs to AlignmentHelper

GitOrigin-RevId: 789501ac3abcb607d643cded52b1043bf3066c9f

platform/code-style-impl/src/com/intellij/formatting/engine/AlignmentHelper.java

@@ -20,12 +20,34 @@ public class AlignmentHelper {
     ALIGNMENT_PROCESSORS.put(Alignment.Anchor.RIGHT, new RightEdgeAlignmentProcessor());
   }
 
+  /**
+   * There is a possible case that we detect a 'cycled alignment' rules (see {@link #myBackwardShiftedAlignedBlocks}). We want
+   * just to skip processing for such alignments then.
+   * <p/>
+   * This container holds 'bad alignment' objects that should not be processed.
+   */
   private final Set<Alignment> myAlignmentsToSkip = new HashSet<>();
   private final Document myDocument;
   private final BlockIndentOptions myBlockIndentOptions;
 
   private final AlignmentCyclesDetector myCyclesDetector;
 
+  /**
+   * Remembers mappings between backward-shifted aligned block and blocks that cause that shift in order to detect
+   * infinite cycles that may occur when, for example following alignment is specified:
+   * <p/>
+   * <pre>
+   *     int i1     = 1;
+   *     int i2, i3 = 2;
+   * </pre>
+   * <p/>
+   * There is a possible case that <code>'i1'</code>, <code>'i2'</code> and <code>'i3'</code> blocks re-use
+   * the same alignment, hence, <code>'i1'</code> is shifted to right during <code>'i3'</code> processing but
+   * that causes <code>'i2'</code> to be shifted right as wll because it's aligned to <code>'i1'</code> that
+   * increases offset of <code>'i3'</code> that, in turn, causes backward shift of <code>'i1'</code> etc.
+   * <p/>
+   * This map remembers such backward shifts in order to be able to break such infinite cycles.
+   */
   private final Map<LeafBlockWrapper, Set<LeafBlockWrapper>> myBackwardShiftedAlignedBlocks = new HashMap<>();
   private final Map<AbstractBlockWrapper, Set<AbstractBlockWrapper>> myAlignmentMappings = new HashMap<>();