update code documentation after refactoring the debugger

Author: robertbasic

pugdebug/debugger.py

@@ -16,6 +16,7 @@
 
 
 class PugdebugDebugger(QObject):
+
     server = None
 
     connections = deque()
@@ -42,15 +43,20 @@ class PugdebugDebugger(QObject):
     def __init__(self):
         """Init the debugger object
 
-        Create a PugdebugServer object used to communicate with xdebug client
-        through TCP.
+        Create a PugdebugServer objects that listens to new connections
+        from xdebug.
 
-        Connect signals to slots.
+        Connect server signals to slots.
         """
         super(PugdebugDebugger, self).__init__()
 
         self.server = PugdebugServer()
 
+        self.connect_server_signals()
+
+    def connect_server_signals(self):
+        """Connect server signals to slots
+        """
         self.server.server_connected_signal.connect(
             self.handle_server_connected
         )
@@ -59,25 +65,38 @@ def __init__(self):
         )
 
     def connect_connection_signals(self, connection):
+        """Connect signals for a new connection
+
+        Connect signals that gets emitted when a connection is stopped
+        or detached, when a step command is done, when variables are read,
+        when stacktraces are read, when breakpoints are set or removed,
+        when breakpoints are read, when expressions are evaluated.
+        """
+
+        # Stop/detach signals
         connection.server_stopped_signal.connect(
             self.handle_server_stopped
         )
         connection.server_detached_signal.connect(
             self.handle_server_stopped
         )
 
+        # Step command signals
         connection.server_stepped_signal.connect(
             self.handle_server_stepped
         )
 
+        # Variables signals
         connection.server_got_variables_signal.connect(
             self.handle_server_got_variables
         )
 
+        # Stacktraces signals
         connection.server_got_stacktraces_signal.connect(
             self.handle_server_got_stacktraces
         )
 
+        # Breakpoints signals
         connection.server_set_init_breakpoints_signal.connect(
             self.handle_server_set_breakpoint
         )
@@ -91,6 +110,7 @@ def connect_connection_signals(self, connection):
             self.handle_server_listed_breakpoints
         )
 
+        # Expressions signals
         connection.server_expression_evaluated_signal.connect(
             self.handle_server_expression_evaluated
         )
@@ -100,6 +120,13 @@ def connect_connection_signals(self, connection):
 
     def cleanup(self):
         """Cleanup debugger when it's done
+
+        If there is an active connection, disconnect from it and clear
+        all the remaining connections.
+
+        Stop the server from listening.
+
+        Clean up attributes.
         """
         if self.is_connected():
             self.current_connection.disconnect()
@@ -113,9 +140,13 @@ def cleanup(self):
         self.current_line = 0
 
     def is_connected(self):
+        """Is there an active connection
+        """
         return self.current_connection is not None
 
     def has_pending_connections(self):
+        """Are there any pending connections?
+        """
         return len(self.connections) > 0
 
     def start_debug(self):
@@ -126,9 +157,13 @@ def start_debug(self):
         self.server.connect()
 
     def handle_server_connected(self, connection):
-        """Handle when server gets connected
+        """Handle when the server establishes a new connection
+
+        Connect the signals for the new connection.
+
+        Add it to the queue of connections.
 
-        Emit a debugging started signal.
+        If there is no active connection, start the new connection.
         """
         self.connect_connection_signals(connection)
 
@@ -138,6 +173,12 @@ def handle_server_connected(self, connection):
             self.start_new_connection()
 
     def start_new_connection(self):
+        """Start a new connection
+
+        Get the first (oldest) connection from the queue, set it's init
+        message as the init message for the session, set it as the current
+        connection and emit the debugging started signal.
+        """
         connection = self.connections.popleft()
         self.init_message = connection.init_message
         self.current_connection = connection
@@ -146,22 +187,27 @@ def start_new_connection(self):
 
     def stop_debug(self):
         """Stop a debugging session
+
+        If there is an active connection, stop only that one, otherwise
+        stop the server from listening to new connections.
         """
         if self.is_connected():
             self.current_connection.stop()
         else:
             self.server.stop()
 
     def detach_debug(self):
-        """Detach a debugging session
+        """Detach the current connection
         """
         if self.is_connected():
             self.current_connection.detach()
 
     def handle_server_stopped(self):
-        """Handle when server gets disconnected
+        """Handle when a server stopped signal is received
+
+        If there are pending connections, start a new one.
 
-        Emit a debugging stopped signal.
+        Otherwise clean up and emit a server stopped signal.
         """
         if self.has_pending_connections():
             self.start_new_connection()

pugdebug/pugdebug.py

@@ -136,42 +136,53 @@ def connect_toolbar_action_signals(self):
     def connect_debugger_signals(self):
         """Connect debugger signals
 
-        Connect signal that gets emitted when the debugging is started.
+        Connecting signals that get emitted when a session starts or stops,
+        when a step command is completed, when variables are read, when
+        stacktraces are read, when a breakpoint gets removed, when breakpoints
+        are read, when one or more expressions are evaluated.
 
-        Connect signal that gets emmitted when the debugging is stopped.
-
-        Connect signal that gets emitted when a step command is execute.
-
-        Connect signal that gets emitted when all variables from xdebug are
-        read.
+        Connect signal that gets emitted when an error happens during the
+        debugging session.
         """
 
+        # Start/stop signals
         self.debugger.debugging_started_signal.connect(
             self.handle_debugging_started
         )
         self.debugger.debugging_stopped_signal.connect(
             self.handle_debugging_stopped
         )
+
+        # Step command signals
         self.debugger.step_command_signal.connect(self.handle_step_command)
+
+        # Variables signals
         self.debugger.got_all_variables_signal.connect(
             self.handle_got_all_variables
         )
+
+        # Stacktraces signals
         self.debugger.got_stacktraces_signal.connect(
             self.handle_got_stacktraces
         )
+
+        # Breakpoints signals
         self.debugger.breakpoint_removed_signal.connect(
             self.handle_breakpoint_removed
         )
         self.debugger.breakpoints_listed_signal.connect(
             self.handle_breakpoints_listed
         )
+
+        # Expression signals
         self.debugger.expression_evaluated_signal.connect(
             self.handle_expression_evaluated
         )
         self.debugger.expressions_evaluated_signal.connect(
             self.handle_expressions_evaluated
         )
 
+        # Error signals
         self.debugger.error_signal.connect(
             self.handle_error
         )
@@ -339,9 +350,12 @@ def start_debug(self):
     def handle_debugging_started(self):
         """Handle when debugging starts
 
-        This handler should be called when the connection to
-        xdebug is established and the initial message from xdebug
-        is read.
+        This handle should be called when a new connection is
+        established with xdebug.
+
+        When debugging multiple requests, for example ajax requests,
+        this should be called for every request, as every request
+        has its own connection.
 
         Sets initial breakpoints, breakpoints that were set before the
         debugging session started.
@@ -359,7 +373,11 @@ def handle_debugging_started(self):
     def stop_debug(self):
         """Stop a debugging session
 
-        Stop the currently active debugging session (if any).
+        If the debugging session has a currently active connection,
+        it will stop that connection.
+
+        If there is no active connections, the debugging session will
+        tell the server to stop listening to new connections.
         """
         self.debugger.stop_debug()
 

pugdebug/server.py

@@ -48,6 +48,13 @@ def stop(self):
         self.wait_for_accept = False
 
     def __connect(self):
+        """Connect to the server and listen to new incomming connections
+
+        For every accepted connection, see if it is valid and emit a signal
+        with that new connection.
+
+        Otherwise silently disregard that connection.
+        """
         socket_server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
         socket_server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
         socket_server.settimeout(1)
@@ -122,9 +129,14 @@ def __init__(self, socket):
         self.parser = PugdebugMessageParser()
 
     def init_connection(self):
-        """
-        No need to do this in a new thread, it is already inside
-        a thread separate from the main thread.
+        """Init a new connection
+
+        Read in the init message from xdebug and decide based on the
+        idekey should this connection be accepted or not.
+
+        Do note that it is not needed to call it from a new thread, as
+        it is already called from a thread separate from the main application
+        thread and thus should not block the main thread.
         """
         idekey = get_setting('debugger/idekey')