From 5e4b906e5212d694c4d00545bf87dedcb24f954c Mon Sep 17 00:00:00 2001
From: Bartek Pacia <bartek.pacia@jetbrains.com>
Date: Thu, 11 Sep 2025 01:50:21 +0200
Subject: [PATCH] [code-api] add Javadoc explaining what POM is

Also run the autoformatter on PomRenameableTarget and PomNamedTarget because it looked ugly.

GitOrigin-RevId: 6cea1c66db45eb9a061f388a090535b20816dc15
---
 .../src/com/intellij/pom/PomNamedTarget.java   |  1 -
 .../com/intellij/pom/PomRenameableTarget.java  |  3 +--
 .../src/com/intellij/pom/PomTarget.java        | 18 ++++++++++++++++--
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/platform/core-api/src/com/intellij/pom/PomNamedTarget.java b/platform/core-api/src/com/intellij/pom/PomNamedTarget.java
index dc0b45898db5..043d1ac30a8a 100644
--- a/platform/core-api/src/com/intellij/pom/PomNamedTarget.java
+++ b/platform/core-api/src/com/intellij/pom/PomNamedTarget.java
@@ -19,5 +19,4 @@ public interface PomNamedTarget extends PomTarget {
   PomNamedTarget[] EMPTY_ARRAY = new PomNamedTarget[0];
 
   String getName();
-
 }
diff --git a/platform/core-api/src/com/intellij/pom/PomRenameableTarget.java b/platform/core-api/src/com/intellij/pom/PomRenameableTarget.java
index efb51a7f5b1d..05e495575718 100644
--- a/platform/core-api/src/com/intellij/pom/PomRenameableTarget.java
+++ b/platform/core-api/src/com/intellij/pom/PomRenameableTarget.java
@@ -17,7 +17,7 @@ package com.intellij.pom;
 
 import org.jetbrains.annotations.NotNull;
 
-public interface PomRenameableTarget<T> extends PomNamedTarget{
+public interface PomRenameableTarget<T> extends PomNamedTarget {
 
   boolean isWritable();
 
@@ -26,5 +26,4 @@ public interface PomRenameableTarget<T> extends PomNamedTarget{
    * @return will be ignored unless you use it yourself
    */
   T setName(@NotNull String newName);
-  
 }
diff --git a/platform/core-api/src/com/intellij/pom/PomTarget.java b/platform/core-api/src/com/intellij/pom/PomTarget.java
index c19add8d35e3..fde3310a9c97 100644
--- a/platform/core-api/src/com/intellij/pom/PomTarget.java
+++ b/platform/core-api/src/com/intellij/pom/PomTarget.java
@@ -16,8 +16,22 @@
 package com.intellij.pom;
 
 /**
- * Accompanied by a PSI element via {@link com.intellij.pom.references.PomService#convertToPsi(PomTarget)}. All references to this target
- * should resolve to that PSI element.
+ * An abstract semantic entity defined in terms of some model (a filesystem target, a Spring bean target, etc.).
+ *
+ * <h3>Program Object Model (POM)</h3>
+ * {@code PomTarget} was an attempt to untie code semantics from PSI.
+ * The idea is that references could {@link com.intellij.psi.PsiReference#resolve() resolve} to a {@code PomTarget}
+ * which doesn't necessarily have to be a {@link com.intellij.psi.PsiElement PsiElement} in some PSI tree.
+ * <p>
+ * {@code PomTarget} mimics as {@code PsiElement} ({@link PomTargetPsiElement}) to fit in older APIs.
+ * <p>
+ * The {@code PomTarget}'s accompanying PSI element can be retrieved via {@link com.intellij.pom.references.PomService#convertToPsi(PomTarget) PomService.convertToPsi}.
+ * All references to this target should resolve to that PSI element.
+ * <p>
+ * The current attempt to untie the semantics from PSI is {@link com.intellij.model.Symbol Symbol}.
+ * Prefer using it in new code.
+ * <p>
+ * IntelliJ Program Object Model must not be confused with <a href="https://maven.apache.org/pom.html">Maven's Project Object Model</a>.
  */
 public interface PomTarget extends Navigatable {
   PomTarget[] EMPTY_ARRAY = new PomTarget[0];