diff --git a/java/debugger/openapi/src/com/intellij/debugger/PositionManager.java b/java/debugger/openapi/src/com/intellij/debugger/PositionManager.java
index 86c3d1cbde5c..100ff7793a2d 100644
--- a/java/debugger/openapi/src/com/intellij/debugger/PositionManager.java
+++ b/java/debugger/openapi/src/com/intellij/debugger/PositionManager.java
@@ -24,16 +24,54 @@ import org.jetbrains.annotations.Nullable;
 
 import java.util.List;
 
+/**
+ * Manages the correspondence between source positions and bytecode locations during JVM debugging.
+ * Instances of this class are created by the factory registered via the {@link PositionManagerFactory} extension point.
+ *
+ * @see com.intellij.debugger.engine.JSR45PositionManager
+ */
 public interface PositionManager {
+  /**
+   * Returns the source position corresponding to the specified bytecode location.
+   *
+   * @param location the bytecode location.
+   * @return the corresponding source position.
+   * @throws NoDataException if the location is not in the code managed by this {@code PositionManager}
+   */
   @Nullable
   SourcePosition getSourcePosition(@Nullable Location location) throws NoDataException;
 
+  /**
+   * Returns the list of all Java classes corresponding to the specified position in the source code.
+   *
+   * @param classPosition the source position.
+   * @return the list of corresponding Java classes.
+   * @throws NoDataException if the location is not in the code managed by this {@code PositionManager}
+   */
   @NotNull
   List<ReferenceType> getAllClasses(SourcePosition classPosition) throws NoDataException;
 
+  /**
+   * Returns the list of bytecode locations in a specific class corresponding to the specified position in the source code.
+   *
+   * @param type a Java class (one of the list returned by {@link #getAllClasses}).
+   * @param position the position in the source code.
+   * @return the list of corresponding bytecode locations.
+   * @throws NoDataException if the location is not in the code managed by this {@code PositionManager}
+   */
   @NotNull
   List<Location> locationsOfLine(ReferenceType type, SourcePosition position) throws NoDataException;
 
+  /**
+   * Called to request the JVM to notify the debugger engine when a class corresponding to a breakpoint location is loaded.
+   * The implementation should calculate the pattern of the class files corresponding to the breakpoint location and call
+   * {@link com.intellij.debugger.requests.RequestManager#createClassPrepareRequest} to create the request.
+   *
+   * @param requestor the object to receive the notification from the JVM.
+   * @param position the location of a breakpoint.
+   * @return the prepare request, or null if the code is managed by this {@code PositionManager} but no class prepare notification is needed
+   * @throws NoDataException if the position is not in the code managed by this {@code PositionManager}
+   */
   @Nullable
   ClassPrepareRequest createPrepareRequest(ClassPrepareRequestor requestor, SourcePosition position) throws NoDataException;
 }