From 6c22c5df67b8a1f08e5e2c2772764d488d0c26a6 Mon Sep 17 00:00:00 2001
From: Glenn Jocher <glenn.jocher@ultralytics.com>
Date: Sun, 25 Feb 2024 13:32:58 +0100
Subject: [PATCH] Add docstrings

---
 utils/downloads.py           | 10 +++++-----
 utils/segment/dataloaders.py |  4 +++-
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/utils/downloads.py b/utils/downloads.py
index ccab278a1d00..b2047547eb1c 100644
--- a/utils/downloads.py
+++ b/utils/downloads.py
@@ -11,7 +11,7 @@
 
 
 def is_url(url, check=True):
-    # Check if string is URL and check if URL exists
+    """Determines if a string is a URL and optionally checks its existence online, returning a boolean."""
     try:
         url = str(url)
         result = urllib.parse.urlparse(url)
@@ -22,13 +22,13 @@ def is_url(url, check=True):
 
 
 def gsutil_getsize(url=""):
-    # gs://bucket/file size https://cloud.google.com/storage/docs/gsutil/commands/du
+    """Returns the size in bytes of a file at a Google Cloud Storage URL using `gsutil du`. Returns 0 if the command fails or output is empty."""
     output = subprocess.check_output(["gsutil", "du", url], shell=True, encoding="utf-8")
     return int(output.split()[0]) if output else 0
 
 
 def url_getsize(url="https://ultralytics.com/images/bus.jpg"):
-    # Return downloadable file size in bytes
+    """Returns the size in bytes of a downloadable file at a given URL; defaults to -1 if not found."""
     response = requests.head(url, allow_redirects=True)
     return int(response.headers.get("content-length", -1))
 
@@ -54,7 +54,7 @@ def curl_download(url, filename, *, silent: bool = False) -> bool:
 
 
 def safe_download(file, url, url2=None, min_bytes=1e0, error_msg=""):
-    # Attempts to download file from url or url2, checks and removes incomplete downloads < min_bytes
+    """Downloads a file from a URL (or alternate URL) to a specified path if file is above a minimum size. Removes incomplete downloads."""
     from utils.general import LOGGER
 
     file = Path(file)
@@ -78,7 +78,7 @@ def safe_download(file, url, url2=None, min_bytes=1e0, error_msg=""):
 
 
 def attempt_download(file, repo="ultralytics/yolov5", release="v7.0"):
-    # Attempt file download from GitHub release assets if not found locally. release = 'latest', 'v7.0', etc.
+    """Downloads a file from GitHub release assets or via direct URL if not found locally, supporting backup versions."""
     from utils.general import LOGGER
 
     def github_assets(repository, version="latest"):
diff --git a/utils/segment/dataloaders.py b/utils/segment/dataloaders.py
index b0b3a7424216..9d2e9bef0b09 100644
--- a/utils/segment/dataloaders.py
+++ b/utils/segment/dataloaders.py
@@ -123,6 +123,7 @@ def __init__(
         self.overlap = overlap
 
     def __getitem__(self, index):
+        """Returns a transformed item from the dataset at the specified index, handling indexing and image weighting."""
         index = self.indices[index]  # linear, shuffled, or image_weights
 
         hyp = self.hyp
@@ -230,7 +231,7 @@ def __getitem__(self, index):
         return (torch.from_numpy(img), labels_out, self.im_files[index], shapes, masks)
 
     def load_mosaic(self, index):
-        # YOLOv5 4-mosaic loader. Loads 1 image + 3 random images into a 4-image mosaic
+        """Loads 1 image + 3 random images into a 4-image YOLOv5 mosaic, adjusting labels and segments accordingly."""
         labels4, segments4 = [], []
         s = self.img_size
         yc, xc = (int(random.uniform(-x, 2 * s + x)) for x in self.mosaic_border)  # mosaic center x, y
@@ -291,6 +292,7 @@ def load_mosaic(self, index):
 
     @staticmethod
     def collate_fn(batch):
+        """Custom collation function for DataLoader, batches images, labels, paths, shapes, and segmentation masks."""
         img, label, path, shapes, masks = zip(*batch)  # transposed
         batched_masks = torch.cat(masks, 0)
         for i, l in enumerate(label):