From 986050e4a27eca23daa38f1537fbd00491b3614c Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Sat, 27 Sep 2025 12:39:20 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`pre-for?=
 =?UTF-8?q?-piers-and-use-playback-class`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @bossanova808.

* https://github.com/bossanova808/script.service.playbackresumer/pull/9#issuecomment-3341626055

The following files were modified:

* `resources/lib/monitor.py`
* `resources/lib/playback_resumer.py`
* `resources/lib/player.py`
---
 resources/lib/monitor.py          |  5 ++++
 resources/lib/playback_resumer.py | 11 ++++++---
 resources/lib/player.py           | 41 ++++++++++++++++++++++++++-----
 3 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/resources/lib/monitor.py b/resources/lib/monitor.py
index 3182428..9e24b2e 100644
--- a/resources/lib/monitor.py
+++ b/resources/lib/monitor.py
@@ -11,6 +11,11 @@ def __init__(self, *args, **kwargs):
         Logger.debug('KodiEventMonitor __init__')
 
     def onSettingsChanged(self):
+        """
+        Handle Kodi settings changes by reloading the add-on configuration from settings.
+        
+        Invoked when Kodi reports settings have changed; calls the Store to reload configuration so runtime state reflects updated settings.
+        """
         Logger.info('onSettingsChanged - reload them.')
         Store.load_config_from_settings()
 
diff --git a/resources/lib/playback_resumer.py b/resources/lib/playback_resumer.py
index 83e739a..a979cad 100644
--- a/resources/lib/playback_resumer.py
+++ b/resources/lib/playback_resumer.py
@@ -11,9 +11,14 @@
 
 def run():
     """
-    This is 'main'
-
-    :return:
+    Start the addon: initialize logging and global state, configure Kodi monitor and player, attempt to resume or start playback, then run the main event loop until an abort is requested.
+    
+    This function:
+    - Starts the logger and creates the global Store.
+    - Instantiates and stores Kodi event monitor and player objects.
+    - Attempts to resume previous playback; if nothing resumed and no video is playing, triggers autoplay when enabled.
+    - Enters a loop that waits for an abort request and exits when one is detected.
+    - Stops the logger before returning.
     """
     Logger.start()
     # load settings and create the store for our globals
diff --git a/resources/lib/player.py b/resources/lib/player.py
index b605c2c..eabba4e 100644
--- a/resources/lib/player.py
+++ b/resources/lib/player.py
@@ -19,6 +19,12 @@ class KodiPlayer(xbmc.Player):
 
     # noinspection PyUnusedLocal
     def __init__(self, *args):
+        """
+        Initialize the KodiPlayer instance and bind it to xbmc.Player.
+        
+        Parameters:
+            *args: Optional positional arguments accepted for compatibility; any values passed are ignored.
+        """
         xbmc.Player.__init__(self)
         Logger.debug('KodiPlayer __init__')
 
@@ -33,10 +39,26 @@ def onPlayBackEnded(self):  # video ended normally (user didn't stop it)
         self.autoplay_random_if_enabled()
 
     def onPlayBackStopped(self):
+        """
+        Handle the playback-stopped event and mark the current resume point as managed by Kodi.
+        
+        When playback stops, record a sentinel resume value indicating that Kodi should retain or handle the resume point (internal sentinel -2).
+        """
         Logger.info("onPlayBackStopped")
         self.update_resume_point(-2)
 
     def onPlayBackSeek(self, time_to_seek, seek_offset):
+        """
+        Handle a user-initiated seek during playback and update the stored resume point.
+        
+        When a seek occurs, attempt to record the current playback time as the resume point.
+        If reading the current playback time raises a RuntimeError (e.g., seeked past the end),
+        clear the stored resume point.
+        
+        Parameters:
+            time_to_seek (float): The target time position of the seek (seconds).
+            seek_offset (float): The relative offset of the seek from the previous position (seconds).
+        """
         Logger.info(f'onPlayBackSeek time {time_to_seek}, seekOffset {seek_offset}')
         try:
             self.update_resume_point(self.getTime())
@@ -229,9 +251,12 @@ def update_resume_point(self, seconds):
 
     def resume_if_was_playing(self):
         """
-        Automatically resume a video after a crash, if one was playing...
-
-        :return:
+        Attempt to resume playback after a previous shutdown if resuming is enabled and saved resume data exist.
+        
+        If configured and valid resume data are present, the player will start the saved file and seek to the stored resume time; on any failure or if no resume data are applicable, no playback is resumed.
+        
+        Returns:
+            True if playback was resumed and seeked to the saved position, False otherwise.
         """
 
         if Store.resume_on_startup \
@@ -271,9 +296,13 @@ def resume_if_was_playing(self):
 
     def get_random_library_video(self):
         """
-        Get a random video from the library for playback
-
-        :return:
+        Selects a random video file path from the Kodi library.
+        
+        Chooses among episodes, movies, and music videos and returns the file path of a randomly selected item if one exists. Updates Store.video_types_in_library to reflect whether a given type is present. If the library contains no eligible videos, no selection is made.
+        
+        Returns:
+            str: File path of the selected video.
+            False: If no episodes, movies, or music videos exist in the library.
         """
 
         # Short circuit if library is empty