Add documentation to position mapping

Author: lukel97

src/Haskell/Ide/Engine/Transport/LspStdio.hs

@@ -295,11 +295,58 @@ updatePositionMap uri changes = pluginGetFile "updatePositionMap: " uri $ \file
     return $ IdeResultOk ()
   where
     f (+/-) (J.Range (Position sl sc) (Position el ec)) txt p@(Position l c)
+
+      -- pos is before the change - unaffected
       | l < sl = Just p
+      -- pos is somewhere after the changed line,
+      -- move down the pos to keep it the same
       | l > el = Just $ Position l' c
+
+      {-
+          LEGEND:
+          0-9   char index
+          x     untouched char
+          I/i   inserted/replaced char
+          .     deleted char
+          ^     pos to be converted
+      -}
+
+      {-
+          012345  67
+          xxxxxx  xx
+           ^
+          0123456789
+          xxIIIIiixx
+           ^
+          
+          pos is unchanged if before the edited range
+      -}
       | l == sl && c <= sc = Just p
+
+      {-
+          01234  56
+          xxxxx  xx
+            ^    
+          012345678
+          xxIIIiixx
+                 ^
+          If pos is in the affected range move to after the range
+      -}
       | l == sl && l == el && c <= nec && newL == 0 = Just $ Position l ec
+
+      {-
+          01234  56
+          xxxxx  xx
+                 ^
+          012345678
+          xxIIIiixx
+                 ^
+          If pos is after the affected range, update the char index
+          to keep it in the same place
+      -}
       | l == sl && l == el && c > nec && newL == 0 = Just $ Position l (c +/- (nec - sc))
+
+      -- oh well we tried ¯\_(ツ)_/¯
       | otherwise = Nothing
          where l' = l +/- dl
                dl = newL - oldL