[platform] IJPL-938 Deprecate public utils in com.intellij.refactoring.suggested

Introduced `com.intellij.psi.createSmartPointer`, `com.intellij.psi.util.startOffset`, `com.intellij.psi.util.endOffset`

GitOrigin-RevId: 8f4fab38c57143a0c03aa7b63d26356b103cb445

platform/core-api/src/com/intellij/openapi/editor/rangeMarkers.kt

@@ -0,0 +1,18 @@
+// Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+package com.intellij.openapi.editor
+
+import com.intellij.openapi.util.TextRange
+
+val RangeMarker.asTextRange: TextRange?
+  get() {
+    if (!isValid) return null
+    val start = startOffset
+    val end = endOffset
+    return if (start in 0..end) {
+      TextRange(start, end)
+    }
+    else {
+      // Probably a race condition had happened and range marker is invalidated
+      null
+    }
+  }

platform/core-api/src/com/intellij/psi/smartPointers.kt

@@ -0,0 +1,5 @@
+// Copyright 2000-2024 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+package com.intellij.psi
+
+fun <E : PsiElement> E.createSmartPointer(): SmartPsiElementPointer<E> =
+  SmartPointerManager.getInstance(project).createSmartPsiElementPointer(this)

platform/core-api/src/com/intellij/psi/util/psiTreeUtil.kt

@@ -14,6 +14,12 @@ import org.jetbrains.annotations.ApiStatus
 import java.util.*
 import kotlin.reflect.KClass
 
+val PsiElement.startOffset: Int
+  get() = textRange.startOffset
+
+val PsiElement.endOffset: Int
+  get() = textRange.endOffset
+
 fun PsiElement.validOrNull(): PsiElement? = if (isValid) this else null
 
 // ----------- Walking children/siblings/parents -------------------------------------------------------------------------------------------

platform/lang-api/src/com/intellij/refactoring/suggested/Utils.kt

@@ -3,37 +3,39 @@
 package com.intellij.refactoring.suggested
 
 import com.intellij.openapi.editor.RangeMarker
+import com.intellij.openapi.editor.asTextRange
 import com.intellij.openapi.editor.event.DocumentEvent
 import com.intellij.openapi.util.TextRange
 import com.intellij.psi.PsiElement
 import com.intellij.psi.SmartPointerManager
 import com.intellij.psi.SmartPsiElementPointer
 
+@Suppress("DeprecatedCallableAddReplaceWith")
+@Deprecated("Use TextRange(offset, offset + DocumentEvent.oldLength) directly")
 val DocumentEvent.oldRange: TextRange
   get() = TextRange(offset, offset + oldLength)
 
+@Suppress("DeprecatedCallableAddReplaceWith")
+@Deprecated("Use TextRange(offset, offset + DocumentEvent.newLength) directly")
 val DocumentEvent.newRange: TextRange
   get() = TextRange(offset, offset + newLength)
 
+@Deprecated("Use range from com.intellij.openapi.editor",
+            replaceWith = ReplaceWith("this.asTextRange", "com.intellij.openapi.editor.range.asTextRange"))
 val RangeMarker.range: TextRange?
-  get() {
-    if (!isValid) return null
-    val start = startOffset
-    val end = endOffset
-    return if (start in 0..end) {
-      TextRange(start, end)
-    }
-    else {
-      // Probably a race condition had happened and range marker is invalidated
-      null
-    }
-  }
+  get() = this.asTextRange
 
+@Deprecated("Use PsiElement.startOffset from com.intellij.psi",
+            replaceWith = ReplaceWith("this.startOffset", "com.intellij.psi.util.startOffset"))
 val PsiElement.startOffset: Int
   get() = textRange.startOffset
 
+@Deprecated("Use PsiElement.endOffset from com.intellij.psi",
+            replaceWith = ReplaceWith("this.endOffset", "com.intellij.psi.util.endOffset"))
 val PsiElement.endOffset: Int
   get() = textRange.endOffset
 
+@Deprecated("Use alternative method from com.intellij.psi package",
+            ReplaceWith("this.createSmartPointer()", "com.intellij.psi.createSmartPointer"))
 fun <E : PsiElement> E.createSmartPointer(): SmartPsiElementPointer<E> =
   SmartPointerManager.getInstance(project).createSmartPsiElementPointer(this)