From 37d87e1fdb0c1e8b7029706a28cbdca7e6436ee3 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Wed, 10 Dec 2025 18:04:34 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`improve?=
 =?UTF-8?q?-ui-experience`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @DevStrategist.

* https://github.com/DevStrategist/SubtitleSync/pull/1#issuecomment-3638287164

The following files were modified:

* `subtitle_sync.py`
---
 subtitle_sync.py | 428 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 403 insertions(+), 25 deletions(-)

diff --git a/subtitle_sync.py b/subtitle_sync.py
index abad8da..a8ce93f 100644
--- a/subtitle_sync.py
+++ b/subtitle_sync.py
@@ -43,6 +43,16 @@ class Colors:
 class Tooltip:
     """Modern tooltip implementation"""
     def __init__(self, widget, text, delay=500):
+        """
+        Initialize a Tooltip for a given Tkinter widget.
+        
+        Creates a tooltip instance that will display `text` near `widget` after `delay` milliseconds when the pointer enters the widget; it also binds pointer leave and button events to hide the tooltip.
+        
+        Parameters:
+            widget (tk.Widget): The widget to attach the tooltip to.
+            text (str): The message to display in the tooltip.
+            delay (int): Milliseconds to wait after pointer enter before showing the tooltip.
+        """
         self.widget = widget
         self.text = text
         self.delay = delay
@@ -54,9 +64,26 @@ def __init__(self, widget, text, delay=500):
         widget.bind('<Button>', self.hide)
 
     def schedule_show(self, event=None):
+        """
+        Schedule the tooltip to be shown after the configured delay.
+        
+        Parameters:
+            event (tk.Event | None): Optional event object from the widget binding; ignored by this method.
+        """
         self.scheduled_id = self.widget.after(self.delay, self.show)
 
     def show(self, event=None):
+        """
+        Display the tooltip window positioned below the associated widget.
+        
+        If a tooltip is already visible, this call has no effect. When shown, a borderless
+        Toplevel is created just below the widget and populated with a styled label
+        containing the tooltip text.
+        
+        Parameters:
+            event (tk.Event | None): Optional event object from an event binding; ignored
+                except to match the binding signature.
+        """
         if self.tooltip_window:
             return
 
@@ -77,6 +104,12 @@ def show(self, event=None):
         label.pack()
 
     def hide(self, event=None):
+        """
+        Hide the tooltip and cancel any pending scheduled show.
+        
+        Parameters:
+            event (tk.Event | None): Optional event from an event binding; ignored by this method.
+        """
         if self.scheduled_id:
             self.widget.after_cancel(self.scheduled_id)
             self.scheduled_id = None
@@ -92,7 +125,19 @@ class ModernButton(tk.Canvas):
     """Custom styled button with hover effects"""
     def __init__(self, parent, text, command=None, width=120, height=36,
                  style="primary", tooltip=None):
-        super().__init__(parent, width=width, height=height,
+        """
+                 Create a styled, rounded clickable button widget with optional tooltip.
+                 
+                 Parameters:
+                     parent (tk.Widget): Parent container for the button.
+                     text (str): Label text displayed on the button.
+                     command (callable|None): Optional callable invoked when the button is clicked.
+                     width (int): Width of the button in pixels.
+                     height (int): Height of the button in pixels.
+                     style (str): Visual style key; one of "primary", "secondary", "success", or "danger".
+                     tooltip (str|None): Optional tooltip text shown on hover.
+                 """
+                 super().__init__(parent, width=width, height=height,
                         bg=Colors.BG_MEDIUM, highlightthickness=0, cursor="hand2")
 
         self.text = text
@@ -147,6 +192,11 @@ def __init__(self, parent, text, command=None, width=120, height=36,
             Tooltip(self, tooltip)
 
     def draw(self):
+        """
+        Render the button's current visual state on the canvas.
+        
+        Redraws the entire widget: clears existing items, selects colors based on enabled/disabled and hover state, draws a rounded rectangle background, and centers the button label text.
+        """
         self.delete("all")
         style = self.styles[self.style]
 
@@ -169,6 +219,20 @@ def draw(self):
                         font=("SF Pro Display", 11, "bold"), fill=fg)
 
     def create_rounded_rect(self, x1, y1, x2, y2, r, **kwargs):
+        """
+        Create a rounded rectangle polygon on the canvas.
+        
+        Parameters:
+            x1 (float): Left (minimum) x coordinate of the rectangle.
+            y1 (float): Top (minimum) y coordinate of the rectangle.
+            x2 (float): Right (maximum) x coordinate of the rectangle.
+            y2 (float): Bottom (maximum) y coordinate of the rectangle.
+            r (float): Corner radius; controls the curvature of each corner.
+            **kwargs: Additional options forwarded to Canvas.create_polygon (e.g., fill, outline, width).
+        
+        Returns:
+            int: Canvas item ID of the created polygon.
+        """
         points = [
             x1 + r, y1,
             x2 - r, y1,
@@ -186,31 +250,75 @@ def create_rounded_rect(self, x1, y1, x2, y2, r, **kwargs):
         return self.create_polygon(points, smooth=True, **kwargs)
 
     def on_enter(self, event):
+        """
+        Handle pointer entering the widget to enable hover visuals.
+        
+        Sets the internal hover state and redraws the button unless it is disabled.
+        
+        Parameters:
+            event (tk.Event): The Tkinter event object for the pointer-enter event.
+        """
         if self._state != tk.DISABLED:
             self._hover = True
             self.draw()
 
     def on_leave(self, event):
+        """
+        Handle the mouse leaving the widget by clearing hover state and redrawing the control.
+        
+        Parameters:
+            event (tk.Event): The Tkinter event object for the leave event (may be None).
+        """
         self._hover = False
         self.draw()
 
     def on_click(self, event):
+        """
+        Handle a button press by applying a small visual offset when the widget is enabled.
+        
+        Applies a 1-pixel offset to the button's canvas items to produce a pressed effect if the widget is not disabled.
+        """
         if self._state != tk.DISABLED and self.command:
             # Visual feedback
             self.move("all", 1, 1)
 
     def on_release(self, event):
+        """
+        Handle a mouse/button release on the widget: restore its visual position and invoke the assigned command if enabled.
+        
+        Parameters:
+            event (tk.Event): The Tkinter event object for the release event.
+        """
         if self._state != tk.DISABLED and self.command:
             self.move("all", -1, -1)
             self.command()
 
     def config(self, **kwargs):
+        """
+        Update the widget configuration and apply state-dependent visual changes.
+        
+        If a 'state' keyword is provided, update the internal state, set the cursor to
+        "hand2" when enabled or "arrow" when disabled, and redraw the widget.
+        
+        Parameters:
+            **kwargs: Arbitrary keyword arguments accepted by the widget.
+                state (str, optional): Widget state (e.g., `tk.NORMAL` or `tk.DISABLED`).
+        """
         if "state" in kwargs:
             self._state = kwargs["state"]
             self.configure(cursor="hand2" if self._state != tk.DISABLED else "arrow")
             self.draw()
 
     def configure(self, **kwargs):
+        """
+        Handle widget configuration, intercepting the `state` key to update internal enablement, cursor, and redraw.
+        
+        When `state` is provided, update the widget's internal `_state`, set the cursor to "hand2" when enabled or "arrow" when disabled, and redraw the control. All other keyword arguments are passed through to the base `configure` implementation.
+        
+        Parameters:
+            **kwargs: Configuration options for the widget. Recognized key:
+                state (str): If present, sets the widget's state (e.g., tk.DISABLED) and triggers cursor and visual updates.
+        """
         if "state" in kwargs:
             self._state = kwargs["state"]
             super().configure(cursor="hand2" if self._state != tk.DISABLED else "arrow")
@@ -225,6 +333,18 @@ def configure(self, **kwargs):
 class ModernSpinbox(tk.Frame):
     """Custom styled spinbox with better visuals"""
     def __init__(self, parent, from_=0, to=59, textvariable=None, width=80):
+        """
+        Create a styled numeric spinbox widget with increment/decrement buttons, mouse-wheel support, and focus visuals.
+        
+        Initializes the widget with a numeric range and an associated text variable, builds a contained entry field flanked by decrement and increment controls, and binds focus, click, and mouse-wheel interactions to update the value.
+        
+        Parameters:
+            parent: The parent Tk widget to which this spinbox is attached.
+            from_ (int): Minimum allowed integer value (inclusive).
+            to (int): Maximum allowed integer value (inclusive).
+            textvariable (tk.StringVar | None): Optional StringVar to use for the entry's value; a new one is created when omitted.
+            width (int): Preferred widget width in pixels.
+        """
         super().__init__(parent, bg=Colors.BG_MEDIUM)
 
         self.var = textvariable or tk.StringVar(value=str(from_))
@@ -272,13 +392,35 @@ def __init__(self, parent, from_=0, to=59, textvariable=None, width=80):
         self.container.bind("<MouseWheel>", self.on_mousewheel)
 
     def on_focus_in(self, event):
+        """
+        Set the container's focus border color when the widget receives focus.
+        
+        Updates the container widget's highlightbackground to the focused border color from Colors.
+        """
         self.container.config(highlightbackground=Colors.BORDER_FOCUS)
 
     def on_focus_out(self, event):
+        """
+        Handle loss of focus for the spinbox container.
+        
+        Restores the container's border color to the theme default and validates the current numeric value,
+        clamping or correcting it as necessary.
+        
+        Parameters:
+            event (tk.Event): The focus-out event triggering this handler.
+        """
         self.container.config(highlightbackground=Colors.BORDER)
         self.validate_value()
 
     def validate_value(self):
+        """
+        Clamp the current numeric value in self.var to the allowed range and store it back.
+        
+        Reads the value from self.var, converts it to an integer, clamps it to the range
+        [self.min_val, self.max_val], and writes the clamped integer (as a string)
+        back to self.var. If the current value is not a valid integer, sets self.var to
+        self.min_val.
+        """
         try:
             val = int(self.var.get())
             val = max(self.min_val, min(self.max_val, val))
@@ -287,6 +429,11 @@ def validate_value(self):
             self.var.set(str(self.min_val))
 
     def increment(self, event=None):
+        """
+        Increment the spinbox value by one, clamped to the configured maximum.
+        
+        If the current value parses to an integer and is less than self.max_val, sets the value to current + 1. If the current value is not a valid integer, resets the value to self.min_val. The optional `event` parameter is ignored.
+        """
         try:
             val = int(self.var.get())
             if val < self.max_val:
@@ -295,6 +442,11 @@ def increment(self, event=None):
             self.var.set(str(self.min_val))
 
     def decrement(self, event=None):
+        """
+        Decrease the current numeric value by one if it is greater than the minimum allowed.
+        
+        If the associated variable contains an integer greater than self.min_val, set it to that integer minus one. If the value is at or below self.min_val, leave it unchanged. If the variable cannot be parsed as an integer, reset it to self.min_val.
+        """
         try:
             val = int(self.var.get())
             if val > self.min_val:
@@ -303,6 +455,12 @@ def decrement(self, event=None):
             self.var.set(str(self.min_val))
 
     def on_mousewheel(self, event):
+        """
+        Handle mouse wheel scrolling to adjust the spinbox value.
+        
+        Parameters:
+            event: Mouse wheel event; a positive `event.delta` increments the value, a non-positive `event.delta` decrements it.
+        """
         if event.delta > 0:
             self.increment()
         else:
@@ -315,6 +473,16 @@ def on_mousewheel(self, event):
 class CardFrame(tk.Frame):
     """Modern card-style container"""
     def __init__(self, parent, title=None, **kwargs):
+        """
+        Create a card-style container with an inner content area and an optional title row.
+        
+        When a `title` is provided, a title label and a decorative separator line are added at the top of the inner area. The widget and its inner frame use the module's medium background color; additional keyword arguments are forwarded to the underlying Frame constructor.
+        
+        Parameters:
+            parent: The parent widget in which this CardFrame will be placed.
+            title (str, optional): Text to display as the card's title. If omitted, no title row is created.
+            **kwargs: Additional keyword arguments forwarded to the base tk.Frame initializer (e.g., padding, relief).
+        """
         super().__init__(parent, bg=Colors.BG_MEDIUM, **kwargs)
 
         # Inner container with padding
@@ -333,6 +501,12 @@ def __init__(self, parent, title=None, **kwargs):
                 side=tk.LEFT, fill=tk.X, expand=True, padx=(12, 0), pady=8)
 
     def get_inner(self):
+        """
+        Access the inner content frame of the card.
+        
+        Returns:
+            tk.Frame: The inner frame where child widgets should be placed.
+        """
         return self.inner
 
 
@@ -342,6 +516,12 @@ def get_inner(self):
 class StatusBar(tk.Frame):
     """Modern status bar with animations"""
     def __init__(self, parent):
+        """
+        Create a compact bottom status bar widget containing an icon, a primary status text, a right-aligned info label, and keyboard shortcut hints.
+        
+        Parameters:
+            parent (tk.Widget): Parent/container widget to attach the status bar to. The bar is created with a fixed height of 32 pixels and uses the module's dark theme colors.
+        """
         super().__init__(parent, bg=Colors.BG_DARK, height=32)
         self.pack_propagate(False)
 
@@ -367,6 +547,13 @@ def __init__(self, parent):
         self.shortcut_label.pack(side=tk.RIGHT, padx=12)
 
     def set_status(self, text, status_type="info"):
+        """
+        Update the status bar text and icon color according to a semantic status.
+        
+        Parameters:
+            text (str): Message to display in the status area.
+            status_type (str, optional): One of "info", "success", "warning", "error", or "working" determining the color applied to the icon and text. Defaults to "info".
+        """
         colors = {
             "info": Colors.TEXT_SECONDARY,
             "success": Colors.ACCENT_SUCCESS,
@@ -379,6 +566,12 @@ def set_status(self, text, status_type="info"):
         self.status_label.config(text=text, fg=color)
 
     def set_info(self, text):
+        """
+        Update the right-side informational text displayed in the status bar.
+        
+        Parameters:
+            text (str): Text to show in the info area; use an empty string to clear it.
+        """
         self.info_label.config(text=text)
 
 
@@ -387,6 +580,14 @@ def set_info(self, text):
 # ============================================================================
 class SRTShifter:
     def __init__(self, root):
+        """
+        Initialize the SRTShifter application on the provided Tk root window.
+        
+        Configures the main window (title, size, dark background, HiDPI scaling where available), initializes file-related state, constructs the UI, binds keyboard shortcuts, and sets the initial status message.
+        
+        Parameters:
+            root (tk.Tk): The main Tkinter root window used for the application.
+        """
         self.root = root
         self.root.title("SubtitleSync")
         self.root.geometry("1100x700")
@@ -454,7 +655,14 @@ def create_header(self, parent):
                 bg=Colors.BG_DARK, fg=Colors.TEXT_BRIGHT).pack(side=tk.LEFT)
 
     def create_left_panel(self, parent):
-        """Create the left control panel - compact, no scroll needed"""
+        """
+        Builds and attaches the left-side control panel containing file selection, time-shift inputs, quick presets, and action buttons.
+        
+        Creates and packs the panel into the given parent widget and initializes the widgets and control variables used by the UI. Sets instance attributes for key controls and state: file_label, browse_btn, direction_var, forward_btn, backward_btn, hours_var, minutes_var, seconds_var, milliseconds_var, apply_btn, save_btn, and reset_btn.
+        
+        Parameters:
+            parent (tk.Widget): Container widget to which the left panel will be added.
+        """
         left_panel = tk.Frame(parent, bg=Colors.BG_DARK)
         left_panel.grid(row=0, column=0, sticky="nsew", padx=(0, 10))
 
@@ -567,7 +775,21 @@ def create_left_panel(self, parent):
         self.reset_btn.config(state=tk.DISABLED)
 
     def create_labeled_time_input(self, parent, label, var, min_val, max_val, width=3):
-        """Create a labeled time input"""
+        """
+        Create and pack a compact labeled numeric time input bound to a StringVar.
+        
+        Creates a small labeled input widget (hours/minutes/seconds/milliseconds style) inside `parent`,
+        binds it to `var`, and clamps the entered integer to the inclusive range [min_val, max_val]
+        when the entry loses focus. The widget is packed to the left with a small horizontal gap.
+        
+        Parameters:
+            parent (tk.Widget): Container to pack the labeled input into.
+            label (str): Text label displayed above the input.
+            var (tk.StringVar): Variable holding the input value; updated with the clamped integer string.
+            min_val (int): Minimum allowed integer value; values below are replaced with this on validation.
+            max_val (int): Maximum allowed integer value; values above are replaced with this on validation.
+            width (int, optional): Entry display width in characters. Defaults to 3.
+        """
         container = tk.Frame(parent, bg=Colors.BG_MEDIUM)
         container.pack(side=tk.LEFT, padx=(0, 8))
 
@@ -586,6 +808,14 @@ def create_labeled_time_input(self, parent, label, var, min_val, max_val, width=
         entry.pack(padx=4, pady=4)
 
         def validate(event):
+            """
+            Clamp the integer value in the associated StringVar to the allowed range and correct invalid input.
+            
+            If the current value of `var` parses as an integer, it is clamped to the interval [min_val, max_val] and the clamped integer is written back to `var`. If parsing fails, `var` is set to `min_val`.
+            
+            Parameters:
+                event: The Tkinter event that triggered validation (ignored).
+            """
             try:
                 val = int(var.get())
                 val = max(min_val, min(max_val, val))
@@ -596,7 +826,14 @@ def validate(event):
         entry.bind("<FocusOut>", validate)
 
     def create_right_panel(self, parent):
-        """Create the right preview panel"""
+        """
+        Builds the right-side preview panel containing the subtitle preview and related controls.
+        
+        Creates a framed preview area with a header and a "Sync Line" button, a read-only line-numbers column, the main subtitle Text widget (assigned to self.content_text), and a vertical scrollbar. Configures syntax highlighting tags for timestamps, numbers, and arrows, binds selection, key and mouse-wheel events, and inserts the initial welcome message. Also creates and stores the line numbers widget (self.line_numbers) and the sync button (self.sync_btn).
+        
+        Parameters:
+            parent (tk.Widget): Parent container in which the preview panel will be placed.
+        """
         right_panel = tk.Frame(parent, bg=Colors.BG_DARK)
         right_panel.grid(row=0, column=1, sticky="nsew")
         right_panel.rowconfigure(1, weight=1)
@@ -665,7 +902,11 @@ def create_right_panel(self, parent):
         self.show_welcome_message()
 
     def show_welcome_message(self):
-        """Show welcome message in preview"""
+        """
+        Populate the preview pane with the static welcome message and prepare the preview for read-only display.
+        
+        Inserts the built-in welcome text into the content preview, applies the timestamp highlighting tag for the header line, disables editing of the preview, and refreshes the visible line numbers.
+        """
         self.content_text.config(state=tk.NORMAL)
         self.content_text.delete("1.0", tk.END)
 
@@ -707,13 +948,25 @@ def on_scroll_y(self, *args):
         self.line_numbers.yview(*args)
 
     def on_mousewheel(self, event):
-        """Handle mousewheel scrolling"""
+        """
+        Scroll both the content and line numbers vertically in response to a mouse wheel event.
+        
+        Parameters:
+            event: The mouse wheel event containing a `delta` attribute used to determine scroll direction and amount.
+        
+        Returns:
+            str: `"break"` to stop further event propagation and prevent default scrolling behavior.
+        """
         self.content_text.yview_scroll(int(-1 * (event.delta / 120)), "units")
         self.line_numbers.yview_scroll(int(-1 * (event.delta / 120)), "units")
         return "break"
 
     def update_line_numbers(self, event=None):
-        """Update line numbers display"""
+        """
+        Refresh the line-number gutter so it matches the current number of lines in the content text widget.
+        
+        This updates the read-only `line_numbers` Text widget to contain a numbered list from 1 to the number of lines present in `content_text`. The optional `event` parameter is accepted for use as an event handler but is ignored.
+        """
         self.line_numbers.config(state=tk.NORMAL)
         self.line_numbers.delete("1.0", tk.END)
 
@@ -723,7 +976,11 @@ def update_line_numbers(self, event=None):
         self.line_numbers.config(state=tk.DISABLED)
 
     def highlight_syntax(self):
-        """Apply syntax highlighting to SRT content"""
+        """
+        Apply text tags to the editor content for SRT-specific syntax highlighting.
+        
+        Applies the "timestamp" tag to occurrences of timestamps in the format HH:MM:SS,mmm, the "arrow" tag to all "-->" arrow markers, and the "number" tag to lines that contain only a subtitle index (one or more digits). Existing "timestamp", "arrow", and "number" tags are removed before reapplying.
+        """
         self.content_text.tag_remove("timestamp", "1.0", tk.END)
         self.content_text.tag_remove("number", "1.0", tk.END)
         self.content_text.tag_remove("arrow", "1.0", tk.END)
@@ -751,7 +1008,15 @@ def highlight_syntax(self):
             self.content_text.tag_add("number", start_idx, end_idx)
 
     def bind_shortcuts(self):
-        """Bind keyboard shortcuts"""
+        """
+        Register global keyboard shortcuts on the application root for common actions.
+        
+        Binds:
+        - Command+O: open the file browser to select an SRT file.
+        - Command+S: save the currently shifted content to disk.
+        - Command+Shift+A: apply/preview the current time shift.
+        - Escape: move focus back to the root window.
+        """
         self.root.bind("<Command-o>", lambda e: self.browse_file())
         self.root.bind("<Command-s>", lambda e: self.save_file())
         self.root.bind("<Command-Shift-a>", lambda e: self.preview_shift())
@@ -759,7 +1024,12 @@ def bind_shortcuts(self):
         self.root.bind("<Escape>", lambda e: self.root.focus_set())
 
     def set_direction(self, direction):
-        """Toggle direction selection"""
+        """
+        Set the time-shift direction and update the forward/backward button appearance.
+        
+        Parameters:
+            direction (str): "+" to select forward (advance) or "-" to select backward (delay); updates the internal direction_var and the visual state of the forward/backward buttons.
+        """
         self.direction_var.set(direction)
         if direction == "+":
             self.forward_btn.config(bg=Colors.ACCENT_PRIMARY, fg=Colors.BG_DARK,
@@ -773,7 +1043,14 @@ def set_direction(self, direction):
                                     font=("SF Pro Display", 11, "bold"))
 
     def apply_preset(self, delta_ms):
-        """Add/subtract from current time shift values"""
+        """
+        Adjust the current time-shift inputs by a millisecond delta.
+        
+        Updates the hours, minutes, seconds, and milliseconds StringVars shown in the UI to reflect applying delta_ms to the current configured shift. The current direction control is respected (a "+" applies delta_ms, a "-" applies -delta_ms); if the resulting total shift is negative the direction is flipped and the magnitude is made positive. The hours value is clamped to 23. After updating the input variables, the status bar is set to summarize the adjustment.
+        
+        Parameters:
+            delta_ms (int): Milliseconds to apply to the current shift (can be positive or negative).
+        """
         # Get current total milliseconds
         try:
             current_h = int(self.hours_var.get())
@@ -820,7 +1097,11 @@ def apply_preset(self, delta_ms):
         self.status_bar.set_status(f"Adjusted by {delta_sign}{delta_ms}ms → {sign}{new_h}:{new_m:02d}:{new_s:02d}.{new_ms:03d}", "info")
 
     def browse_file(self):
-        """Open file browser dialog"""
+        """
+        Show a file chooser, load the selected SRT file, and update the UI state.
+        
+        If the user selects a file, store its path on self.file_path, clear any cached shifted content, update the displayed filename, enable or disable the Apply/Sync/Save/Reset controls appropriately, load the file into the preview pane, and update the status bar and subtitle count.
+        """
         file_path = filedialog.askopenfilename(
             title="Select SRT File",
             filetypes=[("SRT files", "*.srt"), ("All files", "*.*")]
@@ -847,14 +1128,25 @@ def browse_file(self):
             self.status_bar.set_info(f"{self.count_subtitles()} subtitles")
 
     def count_subtitles(self):
-        """Count number of subtitles in loaded file"""
+        """
+        Count subtitle entries in the currently loaded SRT content.
+        
+        Counts lines that consist solely of an integer (subtitle index) in the loaded file. Returns 0 if no content is loaded.
+        
+        Returns:
+        	int: Number of subtitle entries found.
+        """
         if not self.original_content:
             return 0
         pattern = r'^\d+\s*$'
         return len(re.findall(pattern, self.original_content, re.MULTILINE))
 
     def load_srt_content(self):
-        """Load and display SRT file content"""
+        """
+        Load the SRT file located at self.file_path and update the preview.
+        
+        Reads the file into self.original_content, populates the preview Text widget with the file contents (with the widget left read-only), applies syntax highlighting, and refreshes the visible line numbers. If no file_path is set the method does nothing. On I/O or parsing errors a modal error dialog is shown via self.show_error.
+        """
         if not self.file_path:
             return
 
@@ -883,7 +1175,14 @@ def on_text_selection(self, event=None):
         pass
 
     def sync_selected_line(self):
-        """Sync a selected subtitle line to a specified timestamp"""
+        """
+        Open a dialog to synchronize the start time of the currently selected subtitle line.
+        
+        This requires an SRT file to be loaded and a text selection that includes a timestamp line
+        in the format "HH:MM:SS,mmm --> HH:MM:SS,mmm". If no file is loaded or the selection
+        does not contain a valid timestamp line, a user-facing warning or error is shown.
+        On success, the function invokes the sync dialog with the selected line's start timestamp.
+        """
         if not self.file_path:
             self.show_error("Error", "Please select an SRT file first.")
             return
@@ -922,7 +1221,14 @@ def sync_selected_line(self):
         self.content_text.config(state=tk.DISABLED)
 
     def show_sync_dialog(self, current_timestamp):
-        """Show modern sync dialog"""
+        """
+        Open a modal dialog to enter a replacement timestamp and apply the computed time shift to the UI.
+        
+        Displays a centered dialog pre-filled with current_timestamp; if the user confirms a valid `HH:MM:SS,mmm` value the function computes the difference between the new and current timestamps, updates the instance's direction and the hours/minutes/seconds/milliseconds input variables, and updates the status bar with a summary of the calculated shift. If the user cancels, no state is changed. If the entered timestamp is invalid, an error dialog is shown and no change is applied.
+        
+        Parameters:
+            current_timestamp (str): The currently-selected timestamp in `HH:MM:SS,mmm` format to be replaced.
+        """
         dialog = tk.Toplevel(self.root)
         dialog.title("Sync Subtitle")
         dialog.geometry("420x340")
@@ -972,6 +1278,11 @@ def show_sync_dialog(self, current_timestamp):
         result = {"confirmed": False, "new_timestamp": None}
 
         def on_confirm():
+            """
+            Validate the timestamp entered by the user; on successful validation set result["confirmed"]
+            to True, store the parsed timestamp string in result["new_timestamp"], and close the dialog.
+            If the format is invalid, display an error message and leave the dialog open.
+            """
             new_timestamp = timestamp_entry.get().strip()
             if not re.match(r'^\d{2}:\d{2}:\d{2},\d{3}$', new_timestamp):
                 self.show_error("Invalid Format",
@@ -982,6 +1293,11 @@ def on_confirm():
             dialog.destroy()
 
         def on_cancel():
+            """
+            Close the modal dialog and destroy its window.
+            
+            This discards any input or pending actions tied to the dialog by destroying the dialog widget.
+            """
             dialog.destroy()
 
         # Buttons
@@ -1035,7 +1351,15 @@ def on_cancel():
         )
 
     def parse_timestamp(self, timestamp):
-        """Parse SRT timestamp to timedelta object"""
+        """
+        Convert an SRT timestamp string (format "HH:MM:SS,mmm") into a timedelta.
+        
+        Parameters:
+            timestamp (str): Timestamp in SRT format "HH:MM:SS,mmm" (hours:minutes:seconds,milliseconds).
+        
+        Returns:
+            timedelta: A datetime.timedelta representing the parsed timestamp, including milliseconds.
+        """
         time_part, ms_part = timestamp.split(',')
         h, m, s = map(int, time_part.split(':'))
         ms = int(ms_part)
@@ -1051,7 +1375,16 @@ def format_timestamp(self, td):
         return f"{hours:02d}:{minutes:02d}:{seconds:02d},{milliseconds:03d}"
 
     def shift_timestamp(self, timestamp, shift_delta):
-        """Shift a timestamp by the given delta"""
+        """
+        Apply a time delta to an SRT timestamp string and return the resulting timestamp.
+        
+        Parameters:
+            timestamp (str): Timestamp in "HH:MM:SS,mmm" format.
+            shift_delta (datetime.timedelta): Time delta to add to the timestamp (may be negative).
+        
+        Returns:
+            str: Resulting timestamp in "HH:MM:SS,mmm" format; values earlier than 00:00:00,000 are clamped to "00:00:00,000".
+        """
         td = self.parse_timestamp(timestamp)
         new_td = td + shift_delta
 
@@ -1061,7 +1394,11 @@ def shift_timestamp(self, timestamp, shift_delta):
         return self.format_timestamp(new_td)
 
     def preview_shift(self):
-        """Apply shift and preview the result"""
+        """
+        Apply the configured time shift to the loaded SRT and update the preview.
+        
+        Reads the currently selected SRT file, shifts every subtitle timestamp by the hours/minutes/seconds/milliseconds and direction set in the UI, stores the result in self.shifted_content, and refreshes the preview (content_text) with syntax highlighting and updated line numbers. Also enables the Save and Reset controls and sets an informative status message. If no file is selected, shows an error and returns; on unexpected errors shows an error dialog and sets the status to error.
+        """
         if not self.file_path:
             self.show_error("Error", "Please select an SRT file first.")
             return
@@ -1092,6 +1429,15 @@ def preview_shift(self):
             timestamp_pattern = r'(\d{2}:\d{2}:\d{2},\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2},\d{3})'
 
             def replace_timestamps(match):
+                """
+                Produce a replacement SRT timestamp line with the matched start and end timestamps shifted by the outer-scope `shift_delta`.
+                
+                Parameters:
+                    match (re.Match): A regex match where group 1 is the start timestamp and group 2 is the end timestamp in "HH:MM:SS,mmm" format.
+                
+                Returns:
+                    str: A timestamp line "HH:MM:SS,mmm --> HH:MM:SS,mmm" where both timestamps have been shifted by `shift_delta`.
+                """
                 start = match.group(1)
                 end = match.group(2)
                 new_start = self.shift_timestamp(start, shift_delta)
@@ -1122,7 +1468,12 @@ def replace_timestamps(match):
             self.status_bar.set_status("Shift failed", "error")
 
     def reset_preview(self):
-        """Reset to original content"""
+        """
+        Restore the preview text to the originally loaded SRT content.
+        
+        Replaces the preview text with `original_content`, reapplies syntax highlighting, refreshes line numbers,
+        clears any stored `shifted_content`, disables the Save and Reset action buttons, and updates the status bar.
+        """
         if self.original_content:
             self.content_text.config(state=tk.NORMAL)
             self.content_text.delete("1.0", tk.END)
@@ -1138,7 +1489,11 @@ def reset_preview(self):
             self.status_bar.set_status("Preview reset to original", "info")
 
     def save_file(self):
-        """Save the shifted content to a file"""
+        """
+        Open a save dialog and write the current shifted SRT content to disk.
+        
+        If no shifted content exists, shows an error and does nothing. Otherwise prompts the user for a save location (defaulting the filename to the original name with `_synced.srt`), writes `self.shifted_content` using UTF-8 encoding, updates the status bar on success, and shows a confirmation dialog. On failure, shows an error dialog describing the problem.
+        """
         if not self.shifted_content:
             self.show_error("Error", "No shifted content to save. Click 'Apply Shift' first.")
             return
@@ -1162,20 +1517,43 @@ def save_file(self):
             self.show_error("Error", f"An error occurred:\n{str(e)}")
 
     def show_error(self, title, message):
-        """Show error dialog"""
+        """
+        Display an error dialog to the user and update the status bar to an error state.
+        
+        Parameters:
+            title (str): Title shown on the error dialog.
+            message (str): Error message displayed in the dialog.
+        """
         messagebox.showerror(title, message)
         self.status_bar.set_status("Error occurred", "error")
 
     def show_warning(self, title, message):
-        """Show warning dialog"""
+        """
+        Display a warning message box to the user.
+        
+        Parameters:
+            title (str): Title text shown in the dialog window.
+            message (str): Warning message body displayed to the user.
+        """
         messagebox.showwarning(title, message)
 
     def show_success(self, title, message):
-        """Show success dialog"""
+        """
+        Display a modal informational dialog indicating a successful operation.
+        
+        Parameters:
+            title (str): The dialog window title.
+            message (str): The message text displayed inside the dialog.
+        """
         messagebox.showinfo(title, message)
 
 
 def main():
+    """
+    Create and run the SRTShifter Tkinter application.
+    
+    Initializes the Tk root window, attempts to set an application icon if available, instantiates SRTShifter with the root, and starts the Tkinter main event loop.
+    """
     root = tk.Tk()
 
     # Set app icon (if available)
@@ -1189,4 +1567,4 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    main()
\ No newline at end of file