From: Mateusz Waronwy <mmzwarowny@dundee.ac.uk>
Date: Wed, 21 Oct 2020 13:45:42 +0000 (+0200)
Subject: JAL-3690 Documentation for AlignCalcManagerI2
X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=924f05754d15d42a60511cc05e233fdf24a448f2;hp=6a6fb5010c2cd06b14a1e055eabaeb4848e65d2d;p=jalview.git

JAL-3690 Documentation for AlignCalcManagerI2
---

diff --git a/src/jalview/api/AlignCalcManagerI2.java b/src/jalview/api/AlignCalcManagerI2.java
index c735c36..756e402 100644
--- a/src/jalview/api/AlignCalcManagerI2.java
+++ b/src/jalview/api/AlignCalcManagerI2.java
@@ -4,23 +4,111 @@ import java.util.List;
 
 import jalview.datamodel.AlignmentAnnotation;
 
+/**
+ * An abstract manager which controls the execution of interactive jobs.
+ * There is always one instance of AlignCancManager per AlignmenViewport
+ * which runs the jobs, notifies observers and ensures no race conditions.
+ * 
+ * @author mmwarowny
+ *
+ */
 public interface AlignCalcManagerI2
 {
+  /**
+   * Registers the worker with the manager and immediately schedules it
+   * for execution.
+   */
   void registerWorker(AlignCalcWorkerI worker);
+  
+  /**
+   * Returns the list of all registered workers or an empty list if 
+   * there are none
+   */
   List<AlignCalcWorkerI> getWorkers();
+  
+  /**
+   * Returns the list of all workers of a given class or an empty list
+   * if there are none. The classes are compared using 
+   * {@ink Class#equals(Object)} rather than {@code instanceof}.
+   */
   List<AlignCalcWorkerI> getWorkersOfClass(Class<? extends AlignCalcWorkerI> cls);
+  
+  /**
+   * Removes the worker from the scheduler. It does not cancel workers
+   * already scheduled for execution.
+   */
   void removeWorker(AlignCalcWorkerI worker);
+  
+  /**
+   * Removes all workers which are involved with the given annotation.
+   */
   void removeWorkerForAnnotation(AlignmentAnnotation annot);
+  
+  /**
+   * Removes all workers of a given class. The classes are compared using
+   * {@link Class#equals(Object)}. 
+   */
   void removeWorkersOfClass(Class<? extends AlignCalcWorkerI> cls);
+  
+  /**
+   * Disables a worker so it won't be run during the following restarts.
+   */
   void disableWorker(AlignCalcWorkerI worker);
+  
+  /**
+   * Restores the previously disabled worker back to operation.
+   */
   void enableWorker(AlignCalcWorkerI worker);
+  
+  /**
+   * Checks whether the worker is disabled either due to failure or
+   * disabling it manually.
+   */
   boolean isDisabled(AlignCalcWorkerI worker);
+  
+  /**
+   * Checks whether the given worker is currently running.
+   */
   boolean isWorking(AlignCalcWorkerI worker);
+  
+  /**
+   * Checks whether the currently running worker (if any) is processing
+   * the given annotation.
+   */
   boolean isWorkingWithAnnotation(AlignmentAnnotation annot);
+  
+  /**
+   * Checks whether this manager is running a worker.
+   */
   boolean isWorking();
+  
+  /**
+   * Scheduler the worker for one-time execution. The worker does not need
+   * to be registered with this manager and will be scheduler regardless
+   * of being disabled. If the worker has already been scheduled, the
+   * previous one will be cancelled.
+   */
   void startWorker(AlignCalcWorkerI worker);
+  
+  /**
+   * Schedules all registered and not-disabled workers for next execution.
+   */
   void restartWorkers();
+  
+  /**
+   * Cancels the execution of the worker. Note, if the worker is already
+   * running, this method may, but doesn't have to, interrupt it in
+   * the middle of the work.
+   */
   void cancelWorker(AlignCalcWorkerI worker);
+  
+  /**
+   * Connect the listener of the worker state changes.
+   */
   void addAlignCalcListener(AlignCalcListener listener);
+  
+  /**
+   * Remove previously registered worker listener.
+   */
   void removeAlignCalcListener(AlignCalcListener listener);
 }