Docstring and API docs udpates

docs/source/reference/plans.rst

@@ -6,3 +6,7 @@ Plans
 .. autofunction:: blop.plans.optimize_step
 
 .. autofunction:: blop.plans.default_acquire
+
+.. autofunction:: blop.plans.acquire_baseline
+
+.. autofunction:: blop.plans.sample_suggestions

src/blop/__init__.py

@@ -1,4 +1,4 @@
-from .ax import Agent, ChoiceDOF, DOFConstraint, Objective, OutcomeConstraint, RangeDOF, ScalarizedObjective
+from .ax import DOF, Agent, ChoiceDOF, DOFConstraint, Objective, OutcomeConstraint, RangeDOF, ScalarizedObjective
 from .plans import acquire_baseline, default_acquire, optimize, optimize_step, sample_suggestions
 
 try:
@@ -10,6 +10,7 @@
     "__version__",
     "Agent",
     "ChoiceDOF",
+    "DOF",
     "DOFConstraint",
     "Objective",
     "OutcomeConstraint",

src/blop/ax/agent.py

@@ -357,18 +357,22 @@ def unsubscribe(self, callback: CallbackBase) -> None:
 
     @property
     def sensors(self) -> Sequence[Sensor]:
+        """The sensors used for data acquisition."""
         return self._sensors
 
     @property
     def actuators(self) -> Sequence[Actuator]:
+        """The actuators that control the degrees of freedom."""
         return self._actuators
 
     @property
     def evaluation_function(self) -> EvaluationFunction:
+        """The function used to evaluate acquired data and produce outcomes."""
         return self._evaluation_function
 
     @property
     def acquisition_plan(self) -> AcquisitionPlan | None:
+        """The acquisition plan for acquiring data, or ``None`` if using the default."""
         return self._acquisition_plan
 
     def to_optimization_problem(self) -> OptimizationProblem:

src/blop/ax/optimizer.py

@@ -87,14 +87,17 @@ def from_checkpoint(cls, checkpoint_path: str) -> "AxOptimizer":
 
     @property
     def checkpoint_path(self) -> str | None:
+        """The file path for saving and restoring optimizer state, or ``None`` if disabled."""
         return self._checkpoint_path
 
     @property
     def ax_client(self) -> Client:
+        """The underlying Ax ``Client`` used for experiment management."""
         return self._client
 
     @property
     def fixed_parameters(self) -> dict[str, Any] | None:
+        """Parameters held fixed during optimization, or ``None`` if all parameters are free."""
         return self._fixed_parameters
 
     @fixed_parameters.setter

src/blop/protocols.py

@@ -254,6 +254,18 @@ def __call__(
 
 @dataclass(frozen=True)
 class BaseOptimizationProblem(Generic[TActuator, TSensor, TPlan]):
+    """Base class for optimization problem definitions.
+
+    Provides the common structure shared by all optimization problem types.
+    Users should use the concrete subclasses :class:`OptimizationProblem` or
+    :class:`QueueserverOptimizationProblem` instead of this class directly.
+
+    See Also
+    --------
+    OptimizationProblem : Concrete problem type for standard usage.
+    QueueserverOptimizationProblem : Concrete problem type for queue server usage.
+    """
+
     optimizer: Optimizer
     actuators: Sequence[TActuator]
     sensors: Sequence[TSensor]