[code-api] add Javadoc explaining what POM is

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

GitOrigin-RevId: 6cea1c66db45eb9a061f388a090535b20816dc15

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();
-
 }

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);
-  
 }

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];