docs(prof.py): add CommandCallback, TimedCallback, WindowCallback protocols

- Defined callback protocols for register_command, register_timed, win_create.
- Fixed Sphinx callable warnings with proper type hints.
- Align docs with the code

apidocs/python/src/prof.py

@@ -10,6 +10,21 @@ Functions are grouped into sections for console interaction, command management,
 autocompletion, window management, chat and room messaging, XMPP operations,
 settings, user/room information, and notifications/logging.
 """
+from typing import Protocol
+
+# Callback Protocols
+# -----------------
+class CommandCallback(Protocol):
+    """Protocol for command callbacks accepting variable string arguments."""
+    def __call__(self, *command_parameters: str) -> None: ...
+
+class TimedCallback(Protocol):
+    """Protocol for timed callbacks accepting no arguments."""
+    def __call__(self) -> None: ...
+
+class WindowCallback(Protocol):
+    """Protocol for window callbacks accepting a window ID and message."""
+    def __call__(self, win_id: str, message: str) -> None: ...
 
 # Console Functions
 # -----------------
@@ -99,13 +114,13 @@ def register_command(
     description: str,
     arguments: list[list[str]],
     examples: list[str],
-    callback: callable,
+    callback: CommandCallback,
 ) -> None:
     """Registers a new command in CProof with help information and a callback.
 
     CProof validates the number of arguments (between min_args and max_args) when
-    the command is invoked. The callback function should accept a list of strings
+    the command is invoked. The callback function accepts variable string arguments
-    representing the command arguments.
+    representing the command parameters.
 
     Args:
         name: The command name, including the leading slash (e.g., ``/say``).
@@ -115,8 +130,7 @@ def register_command(
         description: Short description of the command.
         arguments: List of [argument, description] pairs for help text.
         examples: List of example command invocations.
-        callback: Function to call when the command is executed, taking a list of
+        callback: Function to call when the command is executed, taking variable string arguments.
-            strings as arguments.
 
     Returns:
         None
@@ -125,18 +139,24 @@ def register_command(
 
         ::
 
-            def my_command(args: list[str]) -> None:
+            def command_handler(*args: str) -> None:
                 prof.cons_show(f"Received: {args}")
+                if len(args) == 1 and args[0] in ("on", "off"):
+                    prof.cons_show(f"{args[0].capitalize()}ing something")
+                elif len(args) == 2 and args[0] == "print":
+                    prof.cons_show(args[1])
+                else:
+                    prof.cons_bad_cmd_usage("/new_command")
 
-            synopsis = ["/newcommand action1|action2", "/newcommand print <arg>"]
+            synopsis = ["/new_command on|off", "/new_command print <arg>"]
-            description = "Performs an action or prints an argument."
+            description = "Enables, disables, or prints an argument."
             arguments = [
-                ["action1|action2", "Perform action1 or action2"],
+                ["on|off", "Enable or disable something."],
-                ["print <arg>", "Print the argument"]
+                ["print <arg>", "Print the argument."]
             ]
-            examples = ["/newcommand action1", "/newcommand print 'test'"]
+            examples = ["/new_command on", "/new_command print 'test'"]
             prof.register_command(
-                "/newcommand", 1, 2, synopsis, description, arguments, examples, my_command
+                "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler
             )
     """
     pass
@@ -144,7 +164,7 @@ def register_command(
 # Periodic Callback
 # -----------------
 
-def register_timed(callback: callable, interval: int) -> None:
+def register_timed(callback: TimedCallback, interval: int) -> None:
     """Registers a function to be called periodically by CProof.
 
     Args:
@@ -175,8 +195,7 @@ def completer_add(key: str, items: list[str]) -> None:
     list.
 
     Args:
-        key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or
+        key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``).
-            ``/mycommand action``).
         items: The items to return on autocompletion.
 
     Returns:
@@ -264,16 +283,15 @@ def win_exists(tag: str) -> bool:
     """
     pass
 
-def win_create(tag: str, callback: callable) -> None:
+def win_create(tag: str, callback: WindowCallback) -> None:
-    """Creates a new plugin window with the specified tag.
+    """Creates a plugin window with the specified tag.
 
-    The callback function is invoked when the window receives input, taking a
+    The callback processes input messages, typically using the model from the window
-    single string argument representing the input line.
+    title, and is called with the window tag and message.
 
     Args:
         tag: The tag identifying the plugin window.
-        callback: Function to call when the window receives input, taking a string
+        callback: Function to process window input, taking the window tag and message.
-            argument.
 
     Returns:
         None
@@ -282,10 +300,10 @@ def win_create(tag: str, callback: callable) -> None:
 
         ::
 
-            def window_handler(line: str) -> None:
+            def handler(win_id: str, message: str) -> None:
-                prof.win_show("MyPlugin", f"Received: {line}")
+                prof.win_show(win_id, f"Processed: {message}")
 
-            prof.win_create("MyPlugin", window_handler)
+            prof.win_create("MyPlugin", handler)
     """
     pass