DumbService: javadoc

platform/core-api/src/com/intellij/openapi/project/DumbService.java

@@ -1,4 +1,4 @@
-// Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
 package com.intellij.openapi.project;
 
 import com.intellij.openapi.Disposable;
@@ -24,8 +24,8 @@ import java.util.Collection;
 import java.util.List;
 
 /**
- * A service managing IDEA's 'dumb' mode: when indices are updated in background and the functionality is very much limited.
- * Only the explicitly allowed functionality is available. Usually it's allowed by implementing {@link DumbAware} interface.
+ * A service managing the IDE's 'dumb' mode: when indexes are updated in the background, and the functionality is very much limited.
+ * Only the explicitly allowed functionality is available. Usually, it's allowed by implementing {@link DumbAware} interface.
  *
  * @author peter
  */
@@ -43,8 +43,8 @@ public abstract class DumbService {
   public abstract ModificationTracker getModificationTracker();
 
   /**
-   * @return whether IntelliJ IDEA is in dumb mode, which means that right now indices are updated in background.
-   * IDEA offers only limited functionality at such times, e.g. plain text file editing and version control operations.
+   * @return whether the IDE is in dumb mode, which means that right now indexes are updated in the background.
+   * The IDE offers only limited functionality at such times, e.g., plain text file editing and version control operations.
    */
   public abstract boolean isDumb();
 
@@ -72,11 +72,12 @@ public abstract class DumbService {
   /**
    * Executes the runnable as soon as possible on AWT Event Dispatch when:
    * <ul>
-   *   <li>project is initialized</li>
-   *   <li>and there's no dumb mode in progress</li>
+   * <li>project is initialized</li>
+   * <li>and there's no dumb mode in progress</li>
    * </ul>
    * This may also happen immediately if these conditions are already met.<p/>
    * Note that it's not guaranteed that the dumb mode won't start again during this runnable execution, it should manage that situation explicitly.
+   *
    * @param runnable runnable to run
    */
   public abstract void runWhenSmart(@NotNull Runnable runnable);
@@ -89,8 +90,9 @@ public abstract class DumbService {
   public abstract void waitForSmartMode();
 
   /**
-   * Pause the current thread until dumb mode ends, and then run the read action. Index is guaranteed to be available inside that read action,
+   * Pause the current thread until dumb mode ends, and then run the read action. Indexes are guaranteed to be available inside that read action,
    * unless this method is already called with read access allowed.
+   *
    * @throws ProcessCanceledException if the project is closed during dumb mode
    */
   public <T> T runReadActionInSmartMode(@NotNull final Computable<T> r) {
@@ -118,8 +120,9 @@ public abstract class DumbService {
   }
 
   /**
-   * Pause the current thread until dumb mode ends, and then run the read action. Index is guaranteed to be available inside that read action,
+   * Pause the current thread until dumb mode ends, and then run the read action. Indexes are guaranteed to be available inside that read action,
    * unless this method is already called with read access allowed.
+   *
    * @throws ProcessCanceledException if the project is closed during dumb mode
    */
   public void runReadActionInSmartMode(@NotNull Runnable r) {
@@ -148,9 +151,9 @@ public abstract class DumbService {
 
   /**
    * Pause the current thread until dumb mode ends, and then attempt to execute the runnable. If it fails due to another dumb mode having started,
-   * try again until the runnable is able to complete successfully.
+   * try again until the runnable can complete successfully.
    * It makes sense to use this method when you have a long-running activity consisting of many small read actions, and you don't want to
-   * use a single long read action in order to keep the IDE responsive.
+   * use a single long read action to keep the IDE responsive.
    *
    * @see #runReadActionInSmartMode(Runnable)
    */
@@ -168,14 +171,14 @@ public abstract class DumbService {
   }
 
   /**
-   * Invoke the runnable later on EventDispatchThread AND when IDEA isn't in dumb mode.
-   * The runnable won't be invoked if the project is disposed during dumb mode
+   * Invoke the runnable later on EventDispatchThread AND when IDE isn't in dumb mode.
+   * The runnable won't be invoked if the project is disposed during dumb mode.
    */
   public abstract void smartInvokeLater(@NotNull Runnable runnable);
 
   /**
-   * Invoke the runnable later on EventDispatchThread with the given modality state AND when IDEA isn't in dumb mode.
-   * The runnable won't be invoked if the project is disposed during dumb mode
+   * Invoke the runnable later on EventDispatchThread with the given modality state AND when IDE isn't in dumb mode.
+   * The runnable won't be invoked if the project is disposed during dumb mode.
    */
   public abstract void smartInvokeLater(@NotNull Runnable runnable, @NotNull ModalityState modalityState);
 
@@ -218,9 +221,9 @@ public abstract class DumbService {
   }
 
   /**
-   * Queues a task to be executed in "dumb mode", where access to indices is forbidden. Tasks are executed sequentially
+   * Queues a task to be executed in "dumb mode", where access to indexes is forbidden. Tasks are executed sequentially
    * in background unless {@link #completeJustSubmittedTasks()} is called in the same dispatch thread activity.<p/>
-   *
+   * <p>
    * Tasks can specify custom "equality" policy via their constructor. Calling this method has no effect if an "equal" task is already enqueued (but not yet running).
    */
   public abstract void queueTask(@NotNull DumbModeTask task);
@@ -233,17 +236,30 @@ public abstract class DumbService {
 
   /**
    * Runs the "just submitted" tasks under a modal dialog. "Just submitted" means that tasks were queued for execution
-   * earlier within the same Swing event dispatch thread event processing, and there were no other tasks already running at that moment. Otherwise this method does nothing.<p/>
-   *
+   * earlier within the same Swing event dispatch thread event processing, and there were no other tasks already running at that moment. Otherwise, this method does nothing.<p/>
+   * <p>
    * This functionality can be useful in refactorings (invoked in "smart mode"), when after VFS or root changes
    * (which could start "dumb mode") some reference resolve is required (which again requires "smart mode").<p/>
-   *
+   * <p>
    * Should be invoked on dispatch thread.
    */
   public abstract void completeJustSubmittedTasks();
 
+  /**
+   * Replaces given component temporarily with "Not available until indices are built" label during dumb mode.
+   *
+   * @param dumbUnawareContent Component to wrap.
+   * @param parentDisposable   Parent disposable.
+   * @return Wrapped component.
+   */
   public abstract JComponent wrapGently(@NotNull JComponent dumbUnawareContent, @NotNull Disposable parentDisposable);
 
+  /**
+   * Disables given component temporarily during dumb mode.
+   *
+   * @param component  Component to disable.
+   * @param disposable Parent disposable.
+   */
   public void makeDumbAware(@NotNull final JComponent component, @NotNull Disposable disposable) {
     component.setEnabled(!isDumb());
     getProject().getMessageBus().connect(disposable).subscribe(DUMB_MODE, new DumbModeListener() {
@@ -259,6 +275,11 @@ public abstract class DumbService {
     });
   }
 
+  /**
+   * Show a notification when given action is not available during dumb mode.
+   *
+   * @param message Notification message.
+   */
   public abstract void showDumbModeNotification(@NotNull String message);
 
   public abstract Project getProject();
@@ -273,23 +294,24 @@ public abstract class DumbService {
 
   /**
    * Enables or disables alternative resolve strategies for the current thread.<p/>
-   *
-   * Normally reference resolution uses index, and hence is not available in dumb mode. In some cases, alternative ways
+   * <p>
+   * Normally reference resolution uses indexes, and hence is not available in dumb mode. In some cases, alternative ways
    * of performing resolve are available, although much slower. It's impractical to always use these ways because it'll
    * lead to overloaded CPU (especially given there's also indexing in progress). But for some explicit user actions
-   * (e.g. explicit Goto Declaration) turning these slower methods is beneficial.<p/>
-   *
+   * (e.g., explicit Goto Declaration) turning on these slower methods is beneficial.<p/>
+   * <p>
    * NOTE: even with alternative resolution enabled, methods like resolve(), findClass() etc may still throw
    * {@link IndexNotReadyException}. So alternative resolve is not a panacea, it might help provide navigation in some cases
    * but not in all.<p/>
-   *
-   * A typical usage would involve try-finally, where the alternative resolution is first enabled, then an action is performed,
-   * and then alternative resolution is turned off in the finally block.
+   * <p>
+   * A typical usage would involve {@code try-finally}, where the alternative resolution is first enabled, then an action is performed,
+   * and then alternative resolution is turned off in the {@code finally} block.
    */
   public abstract void setAlternativeResolveEnabled(boolean enabled);
 
   /**
    * Invokes the given runnable with alternative resolve set to true.
+   *
    * @see #setAlternativeResolveEnabled(boolean)
    */
   public void withAlternativeResolveEnabled(@NotNull Runnable runnable) {
@@ -304,6 +326,7 @@ public abstract class DumbService {
 
   /**
    * Invokes the given computable with alternative resolve set to true.
+   *
    * @see #setAlternativeResolveEnabled(boolean)
    */
   public <T, E extends Throwable> T computeWithAlternativeResolveEnabled(@NotNull ThrowableComputable<T, E> runnable) throws E {
@@ -318,6 +341,7 @@ public abstract class DumbService {
 
   /**
    * Invokes the given runnable with alternative resolve set to true.
+   *
    * @see #setAlternativeResolveEnabled(boolean)
    */
   public <E extends Throwable> void runWithAlternativeResolveEnabled(@NotNull ThrowableRunnable<E> runnable) throws E {
@@ -332,13 +356,13 @@ public abstract class DumbService {
 
   /**
    * @return whether alternative resolution is enabled for the current thread.
-   *
    * @see #setAlternativeResolveEnabled(boolean)
    */
   public abstract boolean isAlternativeResolveEnabled();
 
   /**
    * Obsolete, does nothing, just executes the passed runnable.
+   *
    * @see #completeJustSubmittedTasks()
    */
   @SuppressWarnings({"unused"})
@@ -348,7 +372,8 @@ public abstract class DumbService {
   }
 
   /**
-   * Runs a heavy activity and suspends indexing (if any) for this time. The user still has the possibility to manually pause and resume the indexing. In that case, indexing won't be resumed automatically after the activity finishes.
+   * Runs a heavy activity and suspends indexing (if any) for this time. The user still can manually pause and resume the indexing. In that case, indexing won't be resumed automatically after the activity finishes.
+   *
    * @param activityName the text (a noun phrase) to display as a reason for the indexing being paused
    */
   public abstract void suspendIndexingAndRun(@NotNull String activityName, @NotNull Runnable activity);
@@ -359,15 +384,13 @@ public abstract class DumbService {
   public interface DumbModeListener {
 
     /**
-     * The event arrives on EDT
+     * The event arrives on EDT.
      */
     default void enteredDumbMode() {}
 
     /**
-     * The event arrives on EDT
+     * The event arrives on EDT.
      */
     default void exitDumbMode() {}
-
   }
-
 }