From d13f9447f1d06242f0f88b8a839873441faa0c90 Mon Sep 17 00:00:00 2001
From: Mike Montano <EdgesFTW@gmail.com>
Date: Tue, 5 Dec 2023 10:44:48 -0600
Subject: [PATCH] Basic Documentation for runalyzer 'is_gathered' and
 upgrade_db 'upgrade_db' APIs

---
 doc/api.rst           |  2 ++
 logpyle/runalyzer.py  | 15 +++++++++++++++
 logpyle/upgrade_db.py | 34 ++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+)

diff --git a/doc/api.rst b/doc/api.rst
index 59e4d0ad..cdcd3fff 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -2,3 +2,5 @@ API Documentation
 =================
 
 .. automodule:: logpyle
+.. automodule:: logpyle.runalyzer
+.. automodule:: logpyle.upgrade_db
diff --git a/logpyle/runalyzer.py b/logpyle/runalyzer.py
index 57562526..9f2971bf 100644
--- a/logpyle/runalyzer.py
+++ b/logpyle/runalyzer.py
@@ -1,4 +1,9 @@
 #! /usr/bin/env python
+"""
+Runalyzer Functions
+--------------------------------
+.. autofunction:: is_gathered
+"""
 
 import code
 import sqlite3
@@ -459,6 +464,16 @@ def my_sprintf(format: str, arg: str) -> str:
 
 
 def is_gathered(conn: sqlite3.Connection) -> bool:
+    """
+    The function checks whether a connection to an existing
+    database has been gathered.
+
+    Parameters
+    ----------
+    conn
+      SQLite3 connection object
+    """
+
     gathered = False
     # get a list of tables with the name of 'runs'
     res = list(conn.execute("""
diff --git a/logpyle/upgrade_db.py b/logpyle/upgrade_db.py
index 43ee0950..613723fb 100644
--- a/logpyle/upgrade_db.py
+++ b/logpyle/upgrade_db.py
@@ -1,3 +1,8 @@
+"""
+Database Upgrade Functions
+--------------------------------
+.. autofunction:: upgrade_db
+"""
 import shutil
 import sqlite3
 
@@ -58,6 +63,35 @@ def upgrade_conn(conn: sqlite3.Connection) -> sqlite3.Connection:
 def upgrade_db(
         dbfile: str, suffix: str, overwrite: bool
         ) -> None:
+    """
+
+    The function first connects to the original database . If the
+    `overwrite` parameter is True, it simply modifies the existing
+    database and uses the same file name for the upgraded database.
+    Otherwise, a new database is created with a separate filename
+    by appending the given suffix to the original file's base name
+    using `filename + suffix + "." + file_ext`.
+
+    Next, the function prints a message indicating whether it is
+    overwriting or creating a new database and then proceeds to
+    upgrade the database schema version to 3.
+
+    Parameters
+    ----------
+    name
+      Quantity name.
+
+    dbfile
+      A database file path
+
+    suffix
+      a suffix to be appended to the filename for the
+      upgraded database
+
+    overwrite
+      a boolean value indicating
+      whether to overwrite the original database or not
+    """
 
     # original db files
     old_conn = sqlite3.connect(dbfile)