Added some commentary to classes to further define behavior

apps/cli/capabilities/null_capability.py

 from queue import Queue
 from threading import Semaphore
 
+# FIXME: This package doesn't seem installable via conda
 from injector import ClassAssistedBuilder, inject
 
+# FIXME
 from wksp.ifaces import *
 import pathlib
 

shared/workspaces/src/workspaces/interfaces.py

@@ -6,6 +6,7 @@ import inspect
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
+from queue import PriorityQueue
 from threading import Thread
 from typing import Dict, List, Optional, Type
 
@@ -16,7 +17,8 @@ CapabilityName = str
 @dataclass
 class Capability(ABC):
     """
-    A capability
+    A capability, which is a particular workflow setup, intended to accept
+    a certain kind of product and some parameters and produce another product
     """
     name: CapabilityName
     max_jobs: int
@@ -48,7 +50,8 @@ class ProductService(ABC):
 @dataclass
 class CapabilityRequest:
     """
-    A particular capability request
+    A capability request, which couples a capability to a product, representing
+    the expectation of a new product given a set of parameters
     """
     # From wksp0
     capability: Capability
@@ -110,10 +113,15 @@ class QueueRunner(Thread, ABC):
     pass
 
 
+@dataclass
 class CapabilityQueue(ABC):
     """
-    Holds capability requests until they can be executed.
+    Organizes requests in a priority order and makes it possible to control
+    the number of concurrent executions or pause execution altogether
     """
+    queue: PriorityQueue
+    max_concurrency: int
+
     @abstractmethod
     def enqueue(self, request: CapabilityRequest):
         raise NotImplementedError(f'{self.__class__.__name__}.{inspect.stack()[0][3]}')
@@ -177,7 +185,7 @@ FieldLabel = str
 
 class Parameter(ABC):
     """
-    Abstracts parameters needed for running capabilities.
+    Abstracts parameter needed for running capabilities
     """
     @staticmethod
     @abstractmethod
@@ -197,6 +205,11 @@ class Parameter(ABC):
 class CapabilityStep(ABC):
     """
     A step in a capability sequence
+    Types of steps:
+    1. Await QA
+    2. Await workflow
+    3. Await product
+    4. Prepare and run workflow
     """
     next: CapabilityStep
 
@@ -211,11 +224,15 @@ class CapabilityStep(ABC):
 
 @dataclass
 class CapabilityExecution(ABC):
+    """
+    An object representing an executed capability step that has already exited the
+    queue after being executed
+    """
     request: WorkflowRequest
     # FIXME: Will this be a string?
     version: str
     current_step: CapabilityStep
-    sequence: CapabilitySequence
+    sequence: "CapabilitySequence"
 
 
 class CapabilityEngineResponder(ABC):
@@ -238,7 +255,7 @@ class CapabilityEngineResponder(ABC):
 @dataclass
 class CapabilitySequence(ABC):
     """
-    Represents the sequence of events in a capability.
+    Represents the sequence of steps required to run the capability
     """
     steps: List[CapabilityStep]