deprecate obsolete fields and methods in LogicalPosition

platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2015 JetBrains s.r.o.
+ * Copyright 2000-2017 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,7 +18,7 @@ package com.intellij.openapi.editor;
 import org.jetbrains.annotations.NonNls;
 import org.jetbrains.annotations.NotNull;
 
-import java.awt.Point;
+import java.awt.*;
 
 /**
  * Represents a logical position in the editor. Logical positions ignore folding -
@@ -54,6 +54,9 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * Identifies if current logical position may be correctly mapped to visual position. E.g. we can define properties like
    * {@link #softWrapLinesBeforeCurrentLogicalLine}, {@link #softWrapColumnDiff} etc during {@code 'visual position' -> 'logical position'} conversion
    * in order to be able to easy match it back to visual position.
+   *
+   * @deprecated Always <code>false</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final boolean visualPositionAware;
 
@@ -61,6 +64,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * Number of virtual soft wrap-introduced lines before the current logical line.
    *
    * @see #visualPositionAware
+   * @deprecated Always <code>0</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final int softWrapLinesBeforeCurrentLogicalLine;
 
@@ -72,6 +77,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * it will work regardless of whether current {@code LogicalPosition} instance is {@link #visualPositionAware}.
    *
    * @see #visualPositionAware
+   * @deprecated Always <code>0</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final int softWrapLinesOnCurrentLogicalLine;
 
@@ -79,6 +86,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * Number to add to the {@link #column logical column} in order to get soft wrap-introduced visual column offset.
    *
    * @see #visualPositionAware
+   * @deprecated Always <code>0</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final int softWrapColumnDiff;
 
@@ -86,6 +95,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * Number of folded line feeds before the current position.
    *
    * @see #visualPositionAware
+   * @deprecated Always <code>0</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final int foldedLines;
 
@@ -93,6 +104,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * Number to add to the {@link #column logical column} in order to get folding-introduced visual column offset.
    *
    * @see #visualPositionAware
+   * @deprecated Always <code>0</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final int foldingColumnDiff;
 
@@ -108,6 +121,9 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
   /**
    * This field provides the value of {@link VisualPosition#leansRight} field of visual position corresponding to current position.
    * It has meaning only if {@link #visualPositionAware} is set.
+   * 
+   * @deprecated Always <code>false</code> in {@link LogicalPosition} instances returned by platform code since 2016.1. 
+   *             Will be removed in future.
    */
   public final boolean visualPositionLeansRight;
 
@@ -119,12 +135,18 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
     this(line, column, 0, 0, 0, 0, 0, false, leansForward, leansForward);
   }
 
+  /**
+   * @deprecated Use {@link #LogicalPosition(int, int)} instead. Additional fields won't be used in future.
+   */
   public LogicalPosition(int line, int column, int softWrapLinesBeforeCurrentLogicalLine, int softWrapLinesOnCurrentLogicalLine,
                          int softWrapColumnDiff, int foldedLines, int foldingColumnDiff) throws IllegalArgumentException {
     this(line, column, softWrapLinesBeforeCurrentLogicalLine, softWrapLinesOnCurrentLogicalLine, softWrapColumnDiff, foldedLines,
       foldingColumnDiff, true, false, false);
   }
 
+  /**
+   * @deprecated Use {@link #LogicalPosition(int, int, boolean)} instead. Additional fields won't be used in future.
+   */
   public LogicalPosition(int line, int column, int softWrapLinesBeforeCurrentLogicalLine, int softWrapLinesOnCurrentLogicalLine,
                          int softWrapColumnDiff, int foldedLines, int foldingColumnDiff, boolean leansForward,
                          boolean visualPositionLeansRight) throws IllegalArgumentException {
@@ -166,6 +188,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
    * is {@link #visualPositionAware visual position aware}.
    *
    * @return    visual position based on a state of the current logical position
+   *
+   * @deprecated Result doesn't makes sense, since {@link #visualPositionAware} is deprecated.
    */
   public VisualPosition toVisualPosition() {
     return new VisualPosition(
@@ -178,6 +202,8 @@ public class LogicalPosition implements Comparable<LogicalPosition> {
   /**
    * Returns a new instance of class corresponding to the same logical position in the document, but without any cached
    * reference to its visual position.
+   * 
+   * @deprecated Not needed, since {@link #visualPositionAware} is deprecated.
    */
   public LogicalPosition withoutVisualPositionInfo() {
     return new LogicalPosition(line, column, leansForward);