Added more documentation information for residual functions

yolo.py

@@ -4,13 +4,11 @@ TODO: Description
 Sources:
 — https://github.com/wunderwuzzi23/yolo-ai-cmdbot
 """
-
 import os
 import platform
 import subprocess
 import sys
 
-
 import argparse
 import distro
 import dotenv
@@ -80,17 +78,74 @@ def set_openai_api_key(config):
 def print_config(config):
     """
     Print config information.
+
+    Given an input configuration dictionary, this function prints out the
+    current configurations per yolo.yaml. This includes details on "model",
+    "temperature", "max_tokens", "safety", and "shell".
+
+    Parameters
+    ----------
+    config : dict
+        A dictionary containing the various configuration parameters. It should have
+        the following keys: "model", "temperature", "max_tokens", "safety", "shell".
     """
     print("Current configuration per yolo.yaml:")
-    print("* Model        : " + str(config["model"]))
+    print("— Model        : " + str(config["model"]))
-    print("* Temperature  : " + str(config["temperature"]))
+    print("— Temperature  : " + str(config["temperature"]))
-    print("* Max. Tokens  : " + str(config["max_tokens"]))
+    print("— Max. Tokens  : " + str(config["max_tokens"]))
-    print("* Safety       : " + str(bool(config["safety"])))
+    print("— Safety       : " + str(bool(config["safety"])))
-    print("* Shell        : " + str(config["shell"]))
+    print("— Shell        : " + str(config["shell"]))
+
+def get_os_friendly_name():
+    """
+    Returns a friendly name of the user's operating system.
+
+    The function retrieves the current system platform name using the `platform.system()` function.
+    For Linux, it appends the distribution name retrieved from `distro.name(pretty=True)` to give a
+    more descriptive representation. For Darwin (Apple's macOS), it appends "macOS" to "Darwin" to
+    make the output clearer to the user.
+
+    Returns
+    -------
+    str
+        A friendly name for the user's operating system. It will be one of the following:
+
+        - "Linux/<distribution name>"
+        - "Darwin/macOS"
+        - The system string returned by `platform.system()` if it's not Linux or Darwin.
+    """
+    os_name = platform.system()
+
+    if os_name == "Linux":
+        os_name = "Linux/" + distro.name(pretty=True)
+    elif os_name == "Darwin":
+        os_name = "Darwin/macOS"
+
+    return os_name
 
 def get_full_prompt(user_prompt, shell):
     """
-    Construct the prompt, finding the executing directiory so we can find the prompt.txty file.
+    Constructs a full prompt string by appending the user's prompt to a predefined prompt template
+    located in the 'prompt.txt' file.
+
+    The function finds the absolute path of the currently executing file, and based on this path,
+    identifies the directory of 'prompt.txt'. It reads this file, replaces placeholders {shell}
+    and {os} in the text file with a passed shell parameter and the friendly name of the operating
+    system respectively. The user prompt is then appended to this pre-prompt. If the resulting
+    prompt does not end with a question mark or a period, a question mark is added at last.
+
+    Parameters
+    ----------
+    user_prompt : str
+        The prompt supplied by the user to be appended to the pre-prompt.
+    shell : str
+        The shell information to be inserted in the place of {shell} placeholder in 'prompt.txt'.
+
+    Returns
+    -------
+    str
+        The full prompt, constructed from the template prompt in 'prompt.txt',
+        user-provided shell info, the OS name, and the user-supplied prompt string.
     """
     yolo_path = os.path.abspath(__file__)
     prompt_path = os.path.dirname(yolo_path)
@@ -102,25 +157,12 @@ def get_full_prompt(user_prompt, shell):
     pre_prompt = pre_prompt.replace("{os}", get_os_friendly_name())
     prompt = pre_prompt + user_prompt
 
-    # be nice and make it a question
+    # Be nice and make it a question.
     if prompt[-1:] != "?" and prompt[-1:] != ".":
         prompt+="?"
 
     return prompt
 
-def get_os_friendly_name():
-    """
-    Get the name of the operating system.
-    """
-    os_name = platform.system()
-
-    if os_name == "Linux":
-        os_name = "Linux/" + distro.name(pretty=True)
-    elif os_name == "Darwin":
-        os_name = "Darwin/macOS"
-
-    return os_name
-
 def call_open_ai(config, query):
     """
     Do we have a prompt from the user?
@@ -129,7 +171,7 @@ def call_open_ai(config, query):
         print ("No user prompt specified.")
         sys.exit(-1)
 
-    # Load the correct prompt based on Shell and OS and append the user's prompt
+    # Load the correct prompt based on shell and OS and append the user's prompt.
     prompt = get_full_prompt(query, config["shell"])
 
     # Make the first line also the system prompt
@@ -151,7 +193,16 @@ def call_open_ai(config, query):
 
 def check_for_issue(response):
     """
-    Todo
+    Checks the given response for any issues and raise an error when detected.
+
+    The function checks if the supplied text response begins with any of a set of predefined
+    prefixes, which indicate a problem with the response. If such a prefix is found, an error
+    message is printed to the console in red, and the program exits with a -1 status code.
+
+    Parameters
+    ----------
+    response : str
+        A response text string that needs to be examined for any issues.
     """
     prefixes = ("sorry", "i'm sorry", "the question is not clear", "i'm", "i am")
     if response.lower().startswith(prefixes):
@@ -160,7 +211,18 @@ def check_for_issue(response):
 
 def check_for_markdown(response):
     """
-    Odd corner case, sometimes ChatCompletion returns markdown
+    Checks for the presence of markdown formatting (specifically, code snippet markdown) in the
+    provided response.
+
+    This function considers the presence of markdown formatting (specifically, code block
+    formatting marked by ```) in the `response` as an "odd corner case". If such a case is
+    detected, it prints an error message in red, along with the markdown-contained response, and
+    then terminates the program with a -1 status code.
+
+    Parameters
+    ----------
+    response : str
+        A response text string that needs to be examined for markdown formatting.
     """
     if response.count("```",2):
         print(colored(
@@ -170,14 +232,40 @@ def check_for_markdown(response):
 
 def missing_posix_display():
     """
-    Todo
+    Checks if the DISPLAY environment variable is set in a POSIX-compliant shell.
+
+    This function runs a shell subprocess that outputs the value of the DISPLAY environment
+    variable. It then checks if this value is unset (i.e., equals a newline 'b'\\n'') in the
+    current shell environment. If the DISPLAY variable is unset, the function returns `True`
+    indicating a "missing" display; otherwise, it returns `False`.
+
+    Returns
+    -------
+    bool
+        `True` if the DISPLAY environment variable is unset or empty, `False` otherwise.
     """
     display = subprocess.check_output("echo $DISPLAY", shell=True)
+
     return display == b'\n'
 
 def prompt_user_input(config, response):
     """
-    Todo
+    Print the command proposal in blue and prompt the user for next action based on the safety
+    configuration.
+
+    The user is given options to execute, modify, or copy the command to clipboard if the safety
+    configuration is enabled (config["safety"] = True). If the safety configuration is off
+    (config["safety"] = False), the function automatically assumes an execution action ('Y' for
+    Yes). In a POSIX-compliant shell with no display available (checked using
+    `missing_posix_display()`), the 'copy to clipboard' option is omitted.
+
+    Parameters
+    ----------
+    config : dict
+        The system configurations dictionary which contains a "safety" key
+        to determine user prompt options.
+    response : str
+        The proposed command which is to be printed and may be executed by the user.
     """
     print("Command: " + colored(response, 'blue'))
 
@@ -197,7 +285,24 @@ def prompt_user_input(config, response):
 
 def evaluate_input(config, user_input, command):
     """
-    Todo
+    Evaluate the user input to either execute, modify, or copy the command.
+
+    Based on the user's response, this function takes action:
+    - If the user response is 'Y' or blank, the given command gets executed in the shell.
+    - If the user response is 'M', user can modify the command and the modified command is executed
+      recursively.
+    - If the user response is 'C', the command is copied to the clipboard.
+
+    Parameters
+    ----------
+    config : dict
+        The system configurations dictionary. It should contain a "shell" key specifying the shell
+        environment.
+    user_input : str
+        The user response which determines the course of action. It can be 'Y', 'n', 'm', 'c',
+        or '' (empty string).
+    command : str
+        The command which is either executed, modified, or copied to clipboard.
     """
     if user_input.upper() == "Y" or user_input == "":
         if config["shell"] == "powershell.exe":