Apply suggestions from code review

Fix function descriptions and comments

Co-authored-by: Ana María Martínez Gómez <[email protected]>

Author: sara-rn

scripts/utils/generate_package_wiki.py

@@ -4,26 +4,27 @@
 import xml.etree.ElementTree as ET
 from collections import defaultdict
 
+# Dict[str (category), list (packages information)]
 packages_by_category = defaultdict(str)
 
 
 def sort_write_wiki_content(file_path):
-    """ Writes content of packages_by_category to the wiki file
-    
-    This function retrieves rows pertaining to the key category, as a result of
-    iterating over packages_by_category.
-    Writes to the Markdown formatted string:
-    - header with the category name
-    - table with two columns: Package and Description of each of the packages
-    
+    """ Writes package information sorted by category to a Markdown wiki file.
+
+    This function iterates through the `packages_by_category` dictionary, which
+    contains package information organized by category. For each category, it
+    generates a Markdown header and a table containing package names and
+    descriptions. The resulting Markdown content is then written to the specified
+    file.
+
     Args:
-       file_path: path of the wiki .md file
+        file_path (str): The path to the output Markdown file.
     """
     wikiContent = ""
     for category in packages_by_category.keys():
         wikiContent += "## " + category + "\n\n"
         wikiContent += "| Package | Description |\n"
-        wikiContent += "|---|---|\n"
+        wikiContent += "| ------- | ----------- |\n"
         wikiContent += packages_by_category[category] + "\n\n"
     with open(file_path, "w", encoding="utf-8") as f:
         f.write(wikiContent)
@@ -51,12 +52,12 @@ def find_element_text(parent, tag_name):
 def process_packages_directory(packages_dir):
     """ Obtains the package name, description and category from a directory
     
-    This function parses all the nuspec files in the 'packages' directory structure.
+    This function parses all the nuspec files in the specified packages directory.
     It saves into packages_by_category[category] a line containing the package
-    name and the description separated by |
+    name and the description separated by "|".
     
     Args:
-        packages: directory where all the packages reside
+        packages: directory where the packages reside.
     """
     if not os.path.isdir(packages_dir):
         raise FileNotFoundError(f"Packages directory not found: {packages_dir}")
@@ -66,16 +67,16 @@ def process_packages_directory(packages_dir):
         nuspec_metadata = nuspec_tree.find("{*}metadata")
         if nuspec_metadata is not None:
             category = find_element_text(nuspec_metadata, "tags")
-            # we are only interested in the packages with a category
-            # some packages that assist with the istallation (such as common.vm) do
+            # We are only interested in the packages with a category.
+            # Some packages that assist with the istallation (such as common.vm) do
             # not contain a category
             if not category:
                 continue
             description = find_element_text(nuspec_metadata, "description")
             package = find_element_text(nuspec_metadata, "id")
             """packages_by_category is a dictionary of str where each package and description
             are appended formatted in Markdown"""
-            packages_by_category[category] += "|" + package + "|" + description + "|\n"
+            packages_by_category[category] += "| " + package + " | " + description + " |\n"
 
 
 if __name__ == "__main__":