Merge branch 'master' of git.labs.intellij.net:idea/community

build/scripts/libLicenses.gant

@@ -185,7 +185,7 @@ libraryLicense(name: "Saxon-6.5.5", version: "6.5.5", license: "Mozilla Public L
 libraryLicense(name: "Sonatype Nexus: Indexer", libraryName: "nexus-indexer-1.2.3.jar", version: "1.2.3", license: "Eclipse Public License", url: "http://nexus.sonatype.org/", licenseUrl: "http://www.eclipse.org/org/documents/epl-v10.html")
 libraryLicense(name: "Sonatype Nexus: Indexer", libraryName: "nexus-indexer-3.0.4.jar", version: "3.0.4", license: "Eclipse Public License", url: "http://nexus.sonatype.org/", licenseUrl: "http://www.eclipse.org/org/documents/epl-v10.html")
 libraryLicense(name: "SVNKit", libraryName: "svnkit.jar", version: "SVN version, 1.1 branch as of 1 Oct 2007", license: "link (commercial license)", url: "http://www.svnkit.com/", licenseUrl: "http://svnkit.com/license.html")
-libraryLicense(name: "swingx", libraryName: "swingx-core-1.6.2.jar", version: "1.6.2", license: "LGPL 2.1", url: "http://java.net/downloads/swingx/", licenseUrl: "http://www.opensource.org/licenses/lgpl-2.1.php")
+libraryLicense(name: "swingx", libraryName: "swingx", version: "1.6.2", license: "LGPL 2.1", url: "http://java.net/downloads/swingx/", licenseUrl: "http://www.opensource.org/licenses/lgpl-2.1.php")
 libraryLicense(name: "TestNG", version: "5.7 snapshot", license: "Apache 2.0", url: "http://testng.org/doc/", licenseUrl: "http://code.google.com/p/testng/")
 libraryLicense(name: "Trilead SSH", libraryName: "trilead-ssh2", version: "build 213", license: "BSD style (see LICENSE.txt in trilead.jar)", url: "http://www.trilead.com/SSH_Library/")
 libraryLicense(name: "Trove4j", version: "1.1 (with patches by JetBrains)", license: "LGPL", url: "http://trove4j.sourceforge.net/", licenseUrl: "http://trove4j.sourceforge.net/html/license.html")

java/debugger/openapi/src/com/intellij/debugger/PositionManager.java

@@ -24,16 +24,56 @@ 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}
+   * @see com.intellij.debugger.engine.jdi.VirtualMachineProxy#classesByName
+   */
   @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}
+   * @see ReferenceType#locationsOfLine(int)
+   */
   @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;
 }