From 739ac52ff2babe1ed2f5dd8e9301ad8bfda86957 Mon Sep 17 00:00:00 2001
From: Roman Shevchenko <roman.shevchenko@jetbrains.com>
Date: Wed, 8 Apr 2015 19:46:12 +0200
Subject: [PATCH] Cleanup (javadoc; annotations; formatting)

---
 .../openapi/projectRoots/SdkType.java         | 33 ++++++++++++-------
 .../jetbrains/python/sdk/PythonSdkType.java   |  3 +-
 2 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/platform/lang-api/src/com/intellij/openapi/projectRoots/SdkType.java b/platform/lang-api/src/com/intellij/openapi/projectRoots/SdkType.java
index e730709bd439..0411e16894ca 100644
--- a/platform/lang-api/src/com/intellij/openapi/projectRoots/SdkType.java
+++ b/platform/lang-api/src/com/intellij/openapi/projectRoots/SdkType.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2012 JetBrains s.r.o.
+ * Copyright 2000-2015 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -25,7 +25,6 @@ import com.intellij.openapi.vfs.VirtualFile;
 import com.intellij.util.Consumer;
 import com.intellij.util.IconUtil;
 import org.jdom.Element;
-import org.jetbrains.annotations.NonNls;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -40,15 +39,29 @@ public abstract class SdkType implements SdkTypeId {
 
   private final String myName;
 
+  public SdkType(@NotNull String name) {
+    myName = name;
+  }
+
   /**
-   * @return path to set up file chooser to or null if not applicable
+   * Returns a recommended starting path for a file chooser (where SDKs of this type are usually may be found),
+   * or {@code null} if not applicable/no SDKs found.
+   * <p/>
+   * E.g. for Python SDK on Unix the method may return either {@code "/usr/bin"} or {@code "/usr/bin/python"}
+   * (if there is only one Python interpreter installed on a host).
    */
   @Nullable
   public abstract String suggestHomePath();
 
+  /**
+   * Returns a list of all valid SDKs found on this host.
+   * <p/>
+   * E.g. for Python SDK on Unix the method may return {@code ["/usr/bin/python2", "/usr/bin/python3"]}.
+   */
+  @NotNull
   public Collection<String> suggestHomePaths() {
-    String s = suggestHomePath();
-    return s == null ? Collections.<String>emptyList() : Collections.singletonList(s);
+    String home = suggestHomePath();
+    return home != null ? Collections.singletonList(home) : Collections.<String>emptyList();
   }
 
   /**
@@ -58,14 +71,12 @@ public abstract class SdkType implements SdkTypeId {
    * @param homePath the path selected in the file chooser.
    * @return the path to be used as the SDK home.
    */
-
   public String adjustSelectedSdkHome(String homePath) {
     return homePath;
   }
 
   public abstract boolean isValidSdkHome(String path);
 
-
   @Override
   @Nullable
   public String getVersionString(@NotNull Sdk sdk) {
@@ -103,10 +114,6 @@ public abstract class SdkType implements SdkTypeId {
     return loadAdditionalData(additional);
   }
 
-  public SdkType(@NotNull @NonNls String name) {
-    myName = name;
-  }
-
   @NotNull
   @Override
   public String getName() {
@@ -120,7 +127,6 @@ public abstract class SdkType implements SdkTypeId {
   }
 
   @NotNull
-  @NonNls
   public String getHelpTopic() {
     return "preferences.jdks";
   }
@@ -129,6 +135,7 @@ public abstract class SdkType implements SdkTypeId {
     return IconUtil.getAddIcon();
   }
 
+  @Override
   public boolean equals(Object o) {
     if (this == o) return true;
     if (!(o instanceof SdkType)) return false;
@@ -140,10 +147,12 @@ public abstract class SdkType implements SdkTypeId {
     return true;
   }
 
+  @Override
   public int hashCode() {
     return myName.hashCode();
   }
 
+  @Override
   public String toString() {
     return getName();
   }
diff --git a/python/src/com/jetbrains/python/sdk/PythonSdkType.java b/python/src/com/jetbrains/python/sdk/PythonSdkType.java
index 779b1081f58f..228d6597341c 100644
--- a/python/src/com/jetbrains/python/sdk/PythonSdkType.java
+++ b/python/src/com/jetbrains/python/sdk/PythonSdkType.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2000-2014 JetBrains s.r.o.
+ * Copyright 2000-2015 JetBrains s.r.o.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -186,6 +186,7 @@ public class PythonSdkType extends SdkType {
     return null;
   }
 
+  @NotNull
   @Override
   public Collection<String> suggestHomePaths() {
     List<String> candidates = new ArrayList<String>();