ADD doc strings

Author: eleniv3d

src/gh/components/DF_http_listener/code.py

@@ -36,15 +36,21 @@ def RunScript(self,
         sc.sticky.setdefault(f'{prefix}_prev_load', False)  # previous state of toggle
         sc.sticky.setdefault(f'{prefix}_thread_running', False)  # is a background thread running?
 
-        def _import_job(url):
+        def _import_job(url: str):
+
             """
+            Downloads and imports a .ply file from a given URL in a background thread.
             Background job:
             - Downloads the .ply file from the URL
             - Imports it into the active Rhino document
             - Extracts the new geometry (point cloud or mesh)
             - Cleans up the temporary file and document objects
             - Updates sticky state and status message
             - Signals to GH that it should re-solve
+
+            :param url: A string representing a direct URL to a .ply file (e.g. from GitHub or local server).
+                        The file must end with ".ply".
+            :returns: None
             """
 
             tmp = None

src/gh/components/DF_tcp_listener/code.py

@@ -47,7 +47,13 @@ def RunScript(self,
         # Client handler
         def handle_client(conn):
             """
-            reads the incoming bytes from a single client socket and stores valid data in a shared buffer
+            Reads the incoming bytes from a single TCP client socket and stores valid data in a shared buffer.
+
+            :param conn: A socket object returned by `accept()` representing a live client connection.
+                         The client is expected to send newline-delimited JSON-encoded data, where each
+                         message is a list of 6D values: [x, y, z, r, g, b].
+
+            :returns: None
             """
             buf = b''
             with conn:
@@ -72,8 +78,12 @@ def handle_client(conn):
         # thread to accept incoming connections
         def server_loop(sock):
             """
-            runs in its own thread, continuously calling accept() on the listening socket
-            Each time a client connects, it launches a new thread running handle_client to deal with that connection
+            Accepts a single client connection and starts a background thread to handle it.
+
+            :param sock: A bound and listening TCP socket created by start_server().
+                         This socket will accept one incoming connection, then delegate it to handle_client().
+
+            :returns: None. This runs as a background thread and blocks on accept().
             """
             try:
                 conn, _ = sock.accept()
@@ -85,6 +95,8 @@ def server_loop(sock):
         def start_server():
             """
             creates and binds a TCP socket on the given host/port, marks the server as started and then starts the accept_loop in a background thread
+
+            :returns: None.
             """
             sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
             sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
@@ -97,6 +109,11 @@ def start_server():
             threading.Thread(target=server_loop, args=(sock,), daemon=True).start()
 
         def stop_server():
+            """
+            Stops the running TCP server by closing the listening socket and resetting internal state.
+
+            :returns: None.
+            """
             sock = sc.sticky.get(f'{prefix}_server_sock')
             if sock:
                 try:

src/gh/components/DF_websocket_listener/code.py

@@ -67,6 +67,16 @@ def RunScript(self,
         if i_start and not sc.sticky[f'{prefix}_thread_started']:
 
             async def echo(ws, path):
+                """
+                Handles a single WebSocket client connection and reads messages containing point cloud data.
+
+                :param ws: A WebSocket connection object from the 'websockets' server, representing a live client.
+                :param path: The URL path for the connection (unused here but required by the API).
+
+                :returns: None. Updates sc.sticky['ws_last_pcd'] with the most recent valid list of points.
+                          Each message is expected to be a JSON list of 6-element lists:
+                          [x, y, z, r, g, b] for each point.
+                """
                 logs.append("[GH] Client connected")
                 try:
                     async for msg in ws:
@@ -83,6 +93,12 @@ async def echo(ws, path):
                     logs.append(f"Handler crashed: {outer}")
 
             async def server_coro():
+                """
+                Coroutine that starts the WebSocket server and waits for it to be closed.
+
+                :returns: None. Stores the server object in sc.sticky['ws_server'] and the event loop
+                          in sc.sticky['ws_loop']. Also logs progress to sc.sticky['ws_logs'].
+                """
                 loop = asyncio.get_running_loop()
                 sc.sticky[f'{prefix}_loop'] = loop
 
@@ -94,6 +110,11 @@ async def server_coro():
                 logs.append("Server coroutine exited")
 
             def run_server():
+                """
+                Blocking function that runs the WebSocket server coroutine in this thread.
+
+                :returns: None. Used as the target for a background thread. Logs errors if server startup fails.
+                """
                 try:
                     asyncio.run(server_coro())
                 except Exception as ex:

src/gh/diffCheck/diffCheck/df_gh_canvas_utils.py

@@ -11,7 +11,7 @@ def add_str_valuelist(comp,
     indx: int,
     X_param_coord: float,
     Y_param_coord: float,
-    X_offset: int=87
+    X_offset: int = 87
     ) -> None:
     """
         Adds a value list of string values to the component input
@@ -53,7 +53,7 @@ def add_slider(comp,
     default_value: float,
     X_param_coord: float,
     Y_param_coord: float,
-    X_offset: int=100
+    X_offset: int = 100
     ) -> None:
     """
         Adds a slider to the component input
@@ -85,13 +85,13 @@ def add_slider(comp,
         inp.AddSource(slider)  # noqa: F821
 
 
-def add_plane_object(comp, 
-    nickname: str,
-    indx: int,
-    X_param_coord: float,
-    Y_param_coord: float,
-    X_offset: int=75
-    ) -> None:
+def add_plane_object(comp,
+                     nickname: str,
+                     indx: int,
+                     X_param_coord: float,
+                     Y_param_coord: float,
+                     X_offset: int = 75
+                     ) -> None:
     """
         Adds a plane object to the component input
 
@@ -117,7 +117,19 @@ def add_plane_object(comp,
             inp.AddSource(plane)  # noqa: F821
 
 
-def add_button(comp, nickname, indx, x_offset=60):
+def add_button(comp,
+               nickname: str,
+               indx: int,
+               x_offset: int = 60
+               ) -> None:
+    """
+    Adds a one-shot Boolean button to the left of a component input.
+
+    :param comp: The Grasshopper component to which the button will be added.
+    :param nickname: The display label of the button (e.g. "Start", "Load").
+    :param indx: The index of the component input to wire the button into.
+    :param x_offset: Horizontal distance (in pixels) to place the button to the left of the input.
+    """
 
     inp = comp.Params.Input[indx]
     # only add if nothing already connected
@@ -143,7 +155,25 @@ def add_button(comp, nickname, indx, x_offset=60):
         inp.AddSource(btn)
 
 
-def add_panel(comp, nickname, text, indx, x_offset=60, panel_height=20):
+def add_panel(comp,
+              nickname: str,
+              text: str,
+              indx: int,
+              x_offset: int = 60,
+              panel_height: int = 20
+              ) -> None:
+    """
+    Adds a text panel to the left of a component input with a default string value.
+
+    :param comp: The Grasshopper component to which the panel will be added.
+    :param nickname: The label shown at the top of the panel (e.g. "Host", "Port").
+    :param text: The default string to display inside the panel.
+    :param indx: The index of the component input to connect the panel to.
+    :param x_offset: Horizontal distance (in pixels) to place the panel left of the input.
+    :param panel_height: Height of the panel in pixels (default is 20).
+
+    :returns: None. The panel is created, positioned, and connected if no existing source is present.
+    """
 
     inp = comp.Params.Input[indx]
     if inp.SourceCount == 0: