From 7727828fb93e52d32c7a55d05ba0eea93fa6ac84 Mon Sep 17 00:00:00 2001
From: toanmap <toanmap@gmail.com>
Date: Mon, 30 Mar 2026 07:51:03 +0700
Subject: [PATCH] docs: missing docstrings in `ensure_sorted.py`

The `Category` class and its methods (`add_app`, `is_sorted`, `where_unsorted`, `how_to_sort`), as well as the `main` function, lack docstrings. This makes it harder for future maintainers to understand the purpose, arguments, and return values of these components without reading the entire implementation. Given this script is part of the CI pipeline, its clarity is important for project health and maintainability.

Affected files: ensure_sorted.py

Signed-off-by: toanmap <174589430+maptoan@users.noreply.github.com>
---
 ensure_sorted.py | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/ensure_sorted.py b/ensure_sorted.py
index 700c3211..8d4999b9 100755
--- a/ensure_sorted.py
+++ b/ensure_sorted.py
@@ -13,13 +13,26 @@ class bcolors:
     UNDERLINE = '\033[4m'
 
 class Category:
+    """Represents a category of apps in the README.md file."""
     def __init__(self, name):
+        """
+        Initializes a Category object.
+
+        Args:
+            name (str): The name of the category.
+        """
         self.name = name
         # a list of apps
         self.apps = []
 
     def add_app(self, app_str: str):
-        matches = re.findall("(?<=\\[\\*\\*).*(?=\\*\\*\\])", app_str)
+        """
+        Extracts the app name from a markdown string and adds it to the category's app list.
+
+        Args:
+            app_str (str): The markdown string representing an app (e.g., "* [**App Name**](link)").
+        """
+        matches = re.findall("(?<=\[\\*\\*).*(?=\\*\\*\])", app_str)
         if len(matches) != 1:
             raise RuntimeError("These should be only one match")
         app_name = matches[0]
@@ -27,16 +40,34 @@ def add_app(self, app_str: str):
         self.apps.append(app_name.lower())
 
     def is_sorted(self):
+        """
+        Checks if the apps within the category are sorted alphabetically.
+
+        Returns:
+            bool: True if apps are sorted, False otherwise.
+        """
         # I know not effiencent
         return sorted(self.apps) == self.apps
 
-    # Tell exactly where it's unsorted
     def where_unsorted(self):
+        """
+        Identifies and returns a message indicating the first app that is out of order.
+
+        Returns:
+            str: A formatted string showing the unsorted app, or None if sorted.
+        """
         for i in range(1, len(self.apps)):
             if self.apps[i] < self.apps[i-1]:
                 return f'App {bcolors.RED}{self.apps[i-1]}{bcolors.ENDC} is not in the correct order'
 
     def how_to_sort(self):
+        """
+        Compares the current app list with its sorted version to show differences.
+
+        Returns:
+            tuple: A tuple containing two lists: (sorted_apps, unsorted_apps).
+                   Elements in these lists are formatted to highlight differences.
+        """
         sorted_apps = sorted(self.apps)
         unsorted_apps = self.apps.copy()
         for i in range(len(sorted_apps)):
@@ -54,6 +85,10 @@ def __repr__(self):
         return self.__str__()
 
 def main():
+    """
+    Main function to read README.md, parse app categories, and check if apps are sorted.
+    Prints unsorted categories and exits with a non-zero code if any are found.
+    """
     readme_file = open('README.md', 'r')
     # start of the Apps section
     APPS_LINE_START = '## – Apps –\n'
@@ -100,4 +135,4 @@ def main():
         exit(2)
 
 if __name__ == "__main__":
-    main()
+    main()
\ No newline at end of file