Improve documentation in multiple parts

This includes a new admonition for `microgrid.battery_pool()` that
higher values mean higher priorities.

Signed-off-by: Sahas Subramanian <[email protected]>

Author: shsms

src/frequenz/sdk/actor/_power_managing/_matryoshka.py

@@ -1,7 +1,21 @@
 # License: MIT
 # Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 
-"""A power manager implementation that uses the matryoshka algorithm."""
+"""A power manager implementation that uses the matryoshka algorithm.
+
+When there are multiple proposals from different actors for the same set of batteries,
+the matryoshka algorithm will consider the priority of the actors, the bounds they set
+and their preferred power to determine the target power for the batteries.
+
+The preferred power of lower priority actors will take precedence as long as they
+respect the bounds set by higher priority actors.  If lower priority actors request
+power values outside the bounds set by higher priority actors, the target power will
+be the closest value to the preferred power that is within the bounds.
+
+When there is only a single proposal for a set of batteries, its preferred power would
+be the target power, as long as it falls within the system power bounds for the
+batteries.
+"""
 
 from __future__ import annotations
 

src/frequenz/sdk/actor/_power_managing/_power_managing_actor.py

@@ -50,7 +50,6 @@ def __init__(  # pylint: disable=too-many-arguments
             channel_registry: The channel registry.
             algorithm: The power management algorithm to use.
 
-
         Raises:
             NotImplementedError: When an unknown algorithm is given.
         """
@@ -128,8 +127,6 @@ def _add_bounds_tracker(self, battery_ids: frozenset[int]) -> None:
         bounds_receiver = battery_pool._system_power_bounds.new_receiver()
         # pylint: enable=protected-access
 
-        # Fetch the latest system bounds once, before starting the bounds tracker task,
-        # so that when this function returns, there's already some bounds available.
         self._system_bounds[battery_ids] = PowerMetrics(
             timestamp=datetime.now(tz=timezone.utc),
             inclusion_bounds=None,

src/frequenz/sdk/microgrid/_data_pipeline.py

@@ -433,6 +433,13 @@ def battery_pool(
     If a BatteryPool instance for the given ids doesn't exist, a new one is created and
     returned.
 
+    The priority value is used to resolve conflicts when multiple actors are trying to
+    propose different power values for the same set of batteries.
+
+    !!! note
+        When specifying priority, bigger values indicate higher priority. The default
+        priority is the lowest possible value.
+
     The BatteryPool is wrapped in a new `BatteryPoolWrapper` instance each time.
 
     Args:

src/frequenz/sdk/timeseries/battery_pool/_battery_pool_wrapper.py

@@ -49,7 +49,8 @@ def __init__(self, battery_pool: BatteryPool, name: str | None, priority: int):
 
         Args:
             battery_pool: The battery pool to wrap.
-            name: The source ID to use for the requests made by this wrapper.
+            name: An optional name used to identify this instance of the pool or a
+                corresponding actor in the logs.
             priority: The priority of the actor using this wrapper.
         """
         self._battery_pool = battery_pool
@@ -77,15 +78,16 @@ async def propose_power(
         The preferred power of lower priority actors will take precedence as long as
         they respect the bounds set by higher priority actors.  If lower priority actors
         request power values outside of the bounds set by higher priority actors, the
-        target power will be closest value to the preferred power that is within the
+        target power will be the closest value to the preferred power that is within the
         bounds.
 
         When there are no other actors trying to use the same batteries, the actor's
         preferred power would be set as the target power, as long as it falls within the
         system power bounds for the batteries.
 
         The result of the request can be accessed using the receiver returned from the
-        `power_distribution_results` method.
+        `power_status` method, which also streams the bounds that an actor should
+        comply with, based on its priority.
 
         Args:
             power: The power to propose for the batteries in the pool.  If None, the