From d2f697e2fa1f69fdde06d740f5b1f2b7a3c561de Mon Sep 17 00:00:00 2001
From: gmega <giuliano.mega@gmail.com>
Date: Tue, 5 Nov 2024 12:18:47 -0300
Subject: [PATCH] reword docs

---
 benchmarks/core/deluge.py  |  2 ++
 benchmarks/core/network.py | 22 ++++++++++++++--------
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/benchmarks/core/deluge.py b/benchmarks/core/deluge.py
index b2b03e4..cede427 100644
--- a/benchmarks/core/deluge.py
+++ b/benchmarks/core/deluge.py
@@ -19,6 +19,8 @@ logger = logging.getLogger(__name__)
 
 @dataclass(frozen=True)
 class DelugeMeta:
+    """:class:`DelugeMeta` represents the initial metadata required so that a :class:`DelugeNode`
+    can introduce a file into the network, becoming its initial seeder."""
     name: str
     announce_url: Url
 
diff --git a/benchmarks/core/network.py b/benchmarks/core/network.py
index 3baf75a..0df4197 100644
--- a/benchmarks/core/network.py
+++ b/benchmarks/core/network.py
@@ -10,7 +10,7 @@ TInitialMetadata = TypeVar('TInitialMetadata')
 
 
 class DownloadHandle(ABC):
-    """A :class:`DownloadHandle` represents a reference to an underlying download."""
+    """A :class:`DownloadHandle` is a reference to an ongoing download operation."""
 
     @abstractmethod
     def await_for_completion(self, timeout: float = 0) -> bool:
@@ -22,7 +22,7 @@ class DownloadHandle(ABC):
 
 
 class Node(ABC, Generic[TNetworkHandle, TInitialMetadata]):
-    """A :class:`Node` represents a peer within a :class:`FileSharingNetwork`."""
+    """A :class:`Node` represents a peer within a file sharing network."""
 
     @abstractmethod
     def seed(
@@ -34,17 +34,23 @@ class Node(ABC, Generic[TNetworkHandle, TInitialMetadata]):
         Makes the current :class:`Node` a seeder for the specified file.
 
         :param file: local path to the file to seed.
-        :param handle: file sharing requires some initial set of information when a file is first uploaded into the
-            network, and that will typically then result into a compact representation such as a CID or a Torrent file,
-            which other nodes can then use to identify the file and its metadata within the network. This method can
-            take both such initial metadata (TInitialMetadata) or the subsequent network handle (TNetworkHandle) if
-            it exists.
+        :param handle: file sharing typically requires some initial metadata when a file is first uploaded into the
+            network, and this will typically then result into a compact representation such as a manifest CID (Codex)
+            or a Torrent file (Bittorrent) which other nodes can then use to identify and locate both the file and its
+            metadata within the network. When doing an initial seed, this method should be called with the initial
+            metadata (TInitialMetadata). Subsequent calls should use the network handle (TNetworkHandle).
+
+        :return: The network handle (TNetworkHandle) for this file. This handle should be used for subsequent calls to
+            :meth:`seed`.
         """
         pass
 
     @abstractmethod
     def leech(self, handle: TNetworkHandle) -> DownloadHandle:
-        """Makes the current node a leecher for the provided handle."""
+        """Makes the current node a leecher for the provided handle.
+
+        :param handle: a :class:`DownloadHandle`, which can be used to interact with the download process.
+        """
         pass