Improve some documentation comments

Based on the review comments.

Co-authored-by: Sahas Subramanian <[email protected]>
Co-authored-by: Daniel Zullo <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>

Author: 3 people

src/frequenz/sdk/actor/power_distributing/request.py

@@ -12,10 +12,10 @@ class Request:
     """Request to set power to the `PowerDistributingActor`."""
 
     power: int
-    """The amount of power to be set."""
+    """The requested power in watts."""
 
     batteries: set[int]
-    """The set of batteries to use when requesting the power to be set."""
+    """The component ids of the batteries to be used for this request."""
 
     request_timeout_sec: float = 5.0
     """The maximum amount of time to wait for the request to be fulfilled."""
@@ -24,8 +24,8 @@ class Request:
     """Whether to adjust the power to match the bounds.
 
     If `True`, the power will be adjusted (lowered) to match the bounds, so
-    only the decreased power will be set.
+    only the reduced power will be set.
 
     If `False` and the power is outside the batteries' bounds, the request will
-    fail and replied to with an `OutOfBound` result.
+    fail and be replied to with an `OutOfBound` result.
     """

src/frequenz/sdk/actor/power_distributing/result.py

@@ -55,7 +55,7 @@ class _BaseSuccessMixin:
 
 @dataclasses.dataclass
 class Success(_BaseSuccessMixin, Result):  # Order matters here. See above.
-    """Result returned when setting the power succeed for all batteries."""
+    """Result returned when setting the power succeeded for all batteries."""
 
 
 @dataclasses.dataclass