add javadoc (IDEA-CR-11830)
authorSergey Simonchik <sergey.simonchik@jetbrains.com>
Wed, 29 Jun 2016 13:26:55 +0000 (16:26 +0300)
committerSergey Simonchik <sergey.simonchik@jetbrains.com>
Wed, 29 Jun 2016 13:26:55 +0000 (16:26 +0300)
platform/projectModel-impl/src/com/intellij/openapi/roots/AdditionalLibraryRootsProvider.java

index 7155ba1b2af7c6c4d823be92271ed398930b1684..0e57c908d80ff5908f70f9aa7f1902d0904cb090 100644 (file)
@@ -23,9 +23,29 @@ import org.jetbrains.annotations.NotNull;
 import java.util.Collection;
 import java.util.Collections;
 
+/**
+ * Implement this EP to provide additional library roots. It can be useful when it's undesirable to create
+ * {@link com.intellij.openapi.roots.libraries.Library} and attach it to a module via {@link OrderEntry}.
+ * Additional library roots will extend {@link com.intellij.psi.search.GlobalSearchScope#allScope(Project)}
+ * (in UI, "Project and Libraries" scope). Also, files contained in the roots will be shown as library files
+ * in Project View and will be available in "Navigate | File..." popup.
+ *
+ * Please note it is an experimental API that is subject to incompatible changes, or even removal, in a future release.
+ */
 public abstract class AdditionalLibraryRootsProvider {
   public static final ExtensionPointName<AdditionalLibraryRootsProvider> EP_NAME = ExtensionPointName.create("com.intellij.additionalLibraryRootsProvider");
 
+  /**
+   * Returns library source roots (analogous to {@code library.getFiles(OrderRootType.SOURCES)} for a given project.
+   * This method is suitable when it's easier to collect all additional library roots associated with {@code Project},
+   * instead of {@code Module}. E.g. JavaScript libraries can be associated with files or folders allowing more
+   * fine-grained control.
+   * Files contained in the returned roots are considered as library source files:
+   * {@link ProjectFileIndex#isInLibrarySource(VirtualFile)} should return {@code true} for them.
+   *
+   * @param project  Project instance
+   * @return a collection of library source roots
+   */
   @NotNull
   public Collection<VirtualFile> getAdditionalProjectLibrarySourceRoots(@NotNull Project project) {
     return Collections.emptyList();