Merge branch 'build/add-api-docs-gen-tests'

.github/workflows/main.yml

@@ -90,3 +90,31 @@ jobs:
       - name: Check spelling
         run: |
           codespell
+
+  test-c-api-docs:
+    runs-on: ubuntu-latest
+    name: Test C API Documentation Generation
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends make doxygen
+      - name: Test C API docs generation
+        run: |
+          cd apidocs/c/
+          doxygen c-prof.conf
+
+  test-python-api-docs:
+    runs-on: ubuntu-latest
+    name: Test Python API Documentation Generation
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends make python3-sphinx
+      - name: Test Python API docs generation
+        run: |
+          cd apidocs/python/
+          sphinx-apidoc -f -o . src && make -j$(nproc) xml SPHINXOPTS="-W --keep-going -n"

apidocs/c/profapi.h

@@ -450,7 +450,7 @@ int prof_chat_show_themed(char *barejid, char *group, char *item, char *def, cha
 
 /**
 Show a message in a chat room window.
-@param barejid Jabber ID of the room
+@param roomjid Jabber ID of the room
 @param message the message to print
 @return 1 on success, 0 on failure
 */
@@ -459,7 +459,7 @@ int prof_room_show(char *roomjid, char *message);
 /**
 Show a message in a chat room window, using the specified theme, and prefix character
 Themes are specified in ~/.local/share/profanity/plugin_themes
-@param barejid Jabber ID of the room
+@param roomjid Jabber ID of the room
 @param group the group name in the themes file or NULL
 @param item the item name within the group or NULL
 @param def default colour if the theme cannot be found

apidocs/python/conf.py

@@ -1,7 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Profanity Python Plugins API documentation build configuration file, created by
+# CProof Python Plugins API documentation build configuration file.
-# sphinx-quickstart on Thu Mar 17 23:01:31 2016.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
@@ -47,25 +46,25 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Profanity Python Plugins API'
+project = u'CProof Python Plugins API'
-copyright = u'2016 - 2018, boothj5'
+copyright = u'2025, CProof, based on Profanity by boothj5 et al.'
-author = u'boothj5'
+author = u'CProof Developers'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'0.5.0'
+version = u'0.15.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.5.0'
+release = u'0.15.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -75,7 +74,7 @@ language = None
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'modules.rst']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -122,7 +121,7 @@ html_theme = 'default'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = "Profanity Python Plugins"
+html_title = "CProof Python Plugins"
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
@@ -139,7 +138,7 @@ html_title = "Profanity Python Plugins"
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -202,7 +201,7 @@ html_show_copyright = False
 #html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ProfanityPythonPluginsAPIdoc'
+htmlhelp_basename = 'CProofPythonPluginsAPIdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
@@ -224,8 +223,8 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ProfanityPythonPluginsAPI.tex', u'Profanity Python Plugins API Documentation',
+    (master_doc, 'CProofPythonPluginsAPI.tex', u'CProof Python Plugins API Documentation',
-     u'boothj5', 'manual'),
+     u'CProof Developers', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -254,7 +253,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'profanitypythonpluginsapi', u'Profanity Python Plugins API Documentation',
+    (master_doc, 'cproofpythonpluginsapi', u'CProof Python Plugins API Documentation',
      [author], 1)
 ]
 

apidocs/python/index.rst

@@ -1,8 +1,8 @@
-Profanity Python Plugins API
+CProof Python Plugins API
-============================
+===========================
 
-The ``prof`` module describes functions that plugins may call to interact with Profanity.
+The ``prof`` module describes functions that plugins may call to interact with CProof.
-The ``plugin`` module describes functions that plugins may define to be notified of various events in Profanity.
+The ``plugin`` module describes functions that plugins may define to be notified of various events in CProof.
 
 Contents:
 
@@ -11,4 +11,5 @@ Contents:
 
    prof
    plugin
-* :ref:`genindex`
+
+:ref:`genindex`

apidocs/python/src/plugin.py

@@ -1,360 +1,641 @@
 """
-This page describes functions that plugins may implement to be called from Profanity on certain events. All functions are optional.
+The plugin module defines optional callback functions that CProof plugins can
+implement to handle events such as startup, shutdown, message processing, and
+presence updates.
 
-Examples:
 ::
-    def prof_on_start():
-        prof.cons_show("Profanity has started...")
 
-    def prof_pre_room_message_display(room, nick, message):
+    import prof
-        prof.cons_show("Manipulating chat room message before display...")
-        new_message = message + " (added by plugin)"
-        return new_message
 
-    def prof_on_contact_presence(barejid, resource, presence, status, priority):
+All functions are optional and are called by CProof when the corresponding event
-        notify_message = barejid + " is " + presence
+occurs. String parameters and return values are Python 3 str types.
-        prof.notify(notify_message, 5, "Presence")
 """
 
-def prof_init(version, status, account_name, fulljid):
+# Initialization and Lifecycle
-    """Called when a plugin is loaded, either when profanity is started, or when the ``/plugins load`` or ``/plugins install`` commands are called
+# ---------------------------
 
-    :param version: the version of Profanity
+def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
-    :param status: the package status of Profanity, ``"development"`` or ``"release"``
+    """Initializes the plugin when loaded by CProof.
-    :param account_name: account name of the currently logged in account, or ``None`` if not logged in
+
-    :param fulljid: the users full Jabber ID (barejid and resource) if logged in, ``None`` otherwise
+    Called when CProof starts or when the plugin is loaded via the ``/plugins load``
-    :type version: str or unicode
+    or ``/plugins install`` commands.
-    :type status: str or unicode
+
-    :type account_name: str, unicode or None
+    Args:
-    :type fulljid: str, unicode or None
+        version: The version of CProof (e.g., ``"1.0.0"``).
+        status: The package status of CProof (``"development"`` or ``"release"``).
+        account_name: The account name of the logged-in user, or None if not logged in.
+        fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in.
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_init(version: str, status: str, account_name: str | None, fulljid: str | None) -> None:
+                prof.cons_show(f"MyPlugin for CProof {version} ({status}) has been loaded, account: {account_name}")
     """
     pass
 
+def prof_on_start() -> None:
+    """Called when CProof starts.
 
-def prof_on_start():
+    Use this to perform setup tasks that should occur at application startup.
-    """Called when Profanity is started
+
+    Args:
+        None
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_on_start() -> None:
+                prof.cons_show("CProof has started...")
     """
     pass
 
+def prof_on_shutdown() -> None:
+    """Called when CProof is shutting down.
 
-def prof_on_shutdown():
+    Use this to perform cleanup tasks before the application exits.
-    """Called when the user quits Profanity
+
+    Args:
+        None
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_on_shutdown() -> None:
+                prof.cons_show("CProof is shutting down...")
     """
     pass
 
+def prof_on_unload() -> None:
+    """Called when the plugin is unloaded via the ``/plugins unload`` command.
 
-def prof_on_unload():
+    Use this to clean up plugin-specific resources.
-    """Called when a plugin is unloaded with the ``/plugins unload`` command
+
+    Args:
+        None
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_on_unload() -> None:
+                prof.cons_show("Plugin unloaded")
     """
     pass
 
+def prof_on_connect(account_name: str, fulljid: str) -> None:
+    """Called when a user connects to CProof with an account.
 
-def prof_on_connect(account_name, fulljid):
+    Args:
-    """Called when the user connects with an account
+        account_name: The account name used for login.
+        fulljid: The full Jabber ID (barejid/resource) of the connected account.
 
-    :param account_name: account name of the account used for logging in
+    Returns:
-    :param fulljid: the full Jabber ID (barejid and resource) of the account
+        None
-    :type account_name: str or unicode
+
-    :type fulljid: str or unicode
+    Example:
+
+        ::
+
+            def prof_on_connect(account_name: str, fulljid: str) -> None:
+                prof.cons_show(f"Connected as {account_name} ({fulljid})")
     """
     pass
 
+def prof_on_disconnect(account_name: str, fulljid: str) -> None:
+    """Called when a user disconnects an account from CProof.
 
-def prof_on_disconnect(account_name, fulljid):
+    Args:
-    """Called when the user disconnects an account
+        account_name: The account name being disconnected.
+        fulljid: The full Jabber ID (barejid/resource) of the disconnected account.
 
-    :param account_name: account name of the account being disconnected
+    Returns:
-    :param fulljid: the full Jabber ID (barejid and resource) of the account
+        None
-    :type account_name: str or unicode
+
-    :type fulljid: str or unicode
+    Example:
+
+        ::
+
+            def prof_on_disconnect(account_name: str, fulljid: str) -> None:
+                prof.cons_show(f"Disconnected {account_name} ({fulljid})")
     """
     pass
 
+# Chat Message Handlers
+# ---------------------
 
-def prof_pre_chat_message_display(barejid, resource, message):
+def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
-    """Called before a chat message is displayed
+    """Called before a chat message is displayed in a chat window.
 
-    :param barejid: Jabber ID of the message sender
+    Allows the plugin to modify or cancel the message display.
-    :param resource: resource of the message sender
+
-    :param message: the received message
+    Args:
-    :type barejid: str or unicode
+        barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
-    :type resource: str or unicode
+        resource: The sender's resource (e.g., ``laptop``).
-    :type message: str or unicode
+        message: The received message.
-    :return: the new message to display, or ``None`` to preserve the original message
+
-    :rtype: str or unicode
+    Returns:
+        str | None: The modified message to display, or None to preserve the original.
+
+    Example:
+
+        ::
+
+            def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None:
+                new_message = f"{message} (from {barejid})"
+                return new_message
     """
     pass
 
+def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
+    """Called after a chat message is displayed in a chat window.
 
-def prof_post_chat_message_display(barejid, resource, message):
+    Use this to perform actions after the message is shown.
-    """Called after a chat message is displayed
 
-    :param barejid: Jabber ID of the message sender
+    Args:
-    :param resource: resource of the message sender
+        barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``).
-    :param message: the received message
+        resource: The sender's resource (e.g., ``laptop``).
-    :type barejid: str or unicode
+        message: The displayed message.
-    :type resource: str or unicode
+
-    :type message: str or unicode
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None:
+                prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}")
     """
     pass
 
+def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
+    """Called before a chat message is sent from CProof.
 
-def prof_pre_chat_message_send(barejid, message):
+    Allows the plugin to modify or cancel the message.
-    """Called before a chat message is sent
 
-    :param barejid: Jabber ID of the message recipient
+    Args:
-    :param message: the message to be sent
+        barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
-    :type barejid: str or unicode
+        message: The message to be sent.
-    :type message: str or unicode
+
-    :return: the modified or original message to send, or ``None`` to cancel sending of the message
+    Returns:
-    :rtype: str or unicode
+        str | None: The modified message to send, or None to cancel sending.
+
+    Example:
+
+        ::
+
+            def prof_pre_chat_message_send(barejid: str, message: str) -> str | None:
+                return f"{message} (sent by plugin)"
     """
     pass
 
+def prof_post_chat_message_send(barejid: str, message: str) -> None:
+    """Called after a chat message is sent from CProof.
 
-def prof_post_chat_message_send(barejid, message):
+    Use this to log or react to sent messages.
-    """Called after a chat message has been sent
 
-    :param barejid: Jabber ID of the message recipient
+    Args:
-    :param message: the sent message
+        barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``).
-    :type barejid: str or unicode
+        message: The sent message.
-    :type message: str or unicode
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_post_chat_message_send(barejid: str, message: str) -> None:
+                prof.cons_show(f"Sent to {barejid}: {message}")
     """
     pass
 
+# Room Message Handlers
+# ---------------------
 
-def prof_pre_room_message_display(barejid, nick, message):
+def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
-    """Called before a chat room message is displayed
+    """Called before a chat room message is displayed.
 
-    :param barejid: Jabber ID of the room
+    Allows the plugin to modify or cancel the message display.
-    :param nick: nickname of message sender
+
-    :param message: the received message
+    Args:
-    :type barejid: str or unicode
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :type nick: str or unicode
+        nick: The nickname of the message sender.
-    :type message: str or unicode
+        message: The received message.
-    :return: the new message to display, or ``None`` to preserve the original message
+
-    :rtype: str or unicode
+    Returns:
+        str | None: The modified message to display, or None to preserve the original.
+
+    Example:
+
+        ::
+
+            def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None:
+                return f"{message} (from {nick})"
     """
     pass
 
+def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
+    """Called after a chat room message is displayed.
 
-def prof_post_room_message_display(barejid, nick, message):
+    Use this to perform actions after the message is shown.
-    """Called after a chat room message is displayed
 
-    :param barejid: Jabber ID of the room
+    Args:
-    :param nick: nickname of the message sender
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :param message: the received message
+        nick: The nickname of the message sender.
-    :type barejid: str or unicode
+        message: The displayed message.
-    :type nick: str or unicode
+
-    :type message: str or unicode
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None:
+                prof.cons_show(f"Displayed in {barejid} from {nick}: {message}")
     """
     pass
 
+def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
+    """Called before a chat room message is sent.
 
-def prof_pre_room_message_send(barejid, message):
+    Allows the plugin to modify or cancel the message.
-    """Called before a chat room message is sent
 
-    :param barejid: Jabber ID of the room
+    Args:
-    :param message: the message to be sent
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :type barejid: str or unicode
+        message: The message to be sent.
-    :type message: str or unicode
+
-    :return: the modified or original message to send, or ``None`` to cancel sending of the message
+    Returns:
-    :rtype: str or unicode
+        str | None: The modified message to send, or None to cancel sending.
+
+    Example:
+
+        ::
+
+            def prof_pre_room_message_send(barejid: str, message: str) -> str | None:
+                return f"{message} (sent by plugin)"
     """
     pass
 
+def prof_post_room_message_send(barejid: str, message: str) -> None:
+    """Called after a chat room message is sent.
 
-def prof_post_room_message_send(barejid, message):
+    Use this to log or react to sent messages.
-    """Called after a chat room message has been sent
 
-    :param barejid: Jabber ID of the room
+    Args:
-    :param message: the sent message
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :type barejid: str or unicode
+        message: The sent message.
-    :type message: str or unicode
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_post_room_message_send(barejid: str, message: str) -> None:
+                prof.cons_show(f"Sent to {barejid}: {message}")
     """
     pass
 
+def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
+    """Called when a chat room history message is received from the server.
 
-def prof_on_room_history_message(barejid, nick, message, timestamp):
+    Args:
-    """Called when the server sends a chat room history message
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
+        nick: The nickname of the message sender.
+        message: The received message.
+        timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``).
 
-    :param barejid: Jabber ID of the room
+    Returns:
-    :param nick: nickname of the message sender
+        None
-    :param message: the message to be sent
+
-    :param timestamp: time the message was originally sent to the room, in ISO8601 format
+    Example:
-    :type barejid: str or unicode
+
-    :type nick: str or unicode
+        ::
-    :type message: str or unicode
+
-    :type timestamp: str or unicode
+            def prof_on_room_history_message(barejid: str, nick: str, message: str, timestamp: str) -> None:
+                prof.cons_show(f"History in {barejid} from {nick} at {timestamp}: {message}")
     """
     pass
 
+# Private Message Handlers
+# ------------------------
 
-def prof_pre_priv_message_display(barejid, nick, message):
+def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
-    """Called before a private chat room message is displayed
+    """Called before a private chat room message is displayed.
 
-    :param barejid: Jabber ID of the room
+    Allows the plugin to modify or cancel the message display.
-    :param nick: nickname of message sender
+
-    :param message: the received message
+    Args:
-    :type barejid: str or unicode
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :type nick: str or unicode
+        nick: The nickname of the message sender.
-    :type message: str or unicode
+        message: The received message.
-    :return: the new message to display, or ``None`` to preserve the original message
+
-    :rtype: str or unicode
+    Returns:
+        str | None: The modified message to display, or None to preserve the original.
+
+    Example:
+
+        ::
+
+            def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None:
+                return f"{message} (private from {nick})"
     """
     pass
 
+def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
+    """Called after a private chat room message is displayed.
 
-def prof_post_priv_message_display(barejid, nick, message):
+    Use this to perform actions after the message is shown.
-    """Called after a private chat room message is displayed
 
-    :param barejid: Jabber ID of the room
+    Args:
-    :param nick: nickname of the message sender
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :param message: the received message
+        nick: The nickname of the message sender.
-    :type barejid: str or unicode
+        message: The displayed message.
-    :type nick: str or unicode
+
-    :type message: str or unicode
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> None:
+                prof.cons_show(f"Displayed private in {barejid} from {nick}: {message}")
     """
     pass
 
+def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
+    """Called before a private chat room message is sent.
 
-def prof_pre_priv_message_send(barejid, nick, message):
+    Allows the plugin to modify or cancel the message.
-    """Called before a private chat room message is sent
 
-    :param barejid: Jabber ID of the room
+    Args:
-    :param nick: nickname of message recipient
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :param message: the message to be sent
+        nick: The nickname of the message recipient.
-    :type barejid: str or unicode
+        message: The message to be sent.
-    :type nick: str or unicode
+
-    :type message: str or unicode
+    Returns:
-    :return: the modified or original message to send, or ``None`` to cancel sending of the message
+        str | None: The modified message to send, or None to cancel sending.
-    :rtype: str or unicode
+
+    Example:
+
+        ::
+
+            def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None:
+                return f"{message} (private to {nick})"
     """
     pass
 
+def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
+    """Called after a private chat room message is sent.
 
-def prof_post_priv_message_send(barejid, nick, message):
+    Use this to log or react to sent messages.
-    """Called after a private chat room message has been sent
 
-    :param barejid: Jabber ID of the room
+    Args:
-    :param nick: nickname of the message recipient
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
-    :param message: the sent message
+        nick: The nickname of the message recipient.
-    :type barejid: str or unicode
+        message: The sent message.
-    :type nick: str or unicode
+
-    :type message: str or unicode
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None:
+                prof.cons_show(f"Sent private to {nick} in {barejid}: {message}")
     """
     pass
 
+# Stanza Handlers
+# ---------------
 
-def prof_on_message_stanza_send(stanza):
+def prof_on_message_stanza_send(stanza: str) -> str | None:
-    """Called before an XMPP message stanza is sent
+    """Called before an XMPP message stanza is sent.
 
-    :param stanza: The stanza to send
+    Allows the plugin to modify or cancel the stanza.
-    :type stanza: str or unicode
+
-    :return: The new stanza to send, or ``None`` to preserve the original stanza
+    Args:
-    :rtype: str or unicode
+        stanza: The XMPP message stanza to send.
+
+    Returns:
+        str | None: The modified stanza to send, or None to preserve the original.
+
+    Example:
+
+        ::
+
+            def prof_on_message_stanza_send(stanza: str) -> str | None:
+                prof.cons_show(f"Sending message stanza: {stanza}")
+                return stanza
     """
     pass
 
+def prof_on_message_stanza_receive(stanza: str) -> bool:
+    """Called when an XMPP message stanza is received.
 
-def prof_on_message_stanza_receive(stanza):
+    Allows the plugin to control whether CProof processes the stanza.
-    """Called when an XMPP message stanza is received
 
-    :param stanza: The stanza received
+    Args:
-    :type stanza: str or unicode
+        stanza: The received XMPP message stanza.
-    :return: ``True`` if Profanity should continue to process the message stanza, ``False`` otherwise
+
-    :rtype: boolean
+    Returns:
+        bool: True to allow CProof to process the stanza, False to block processing.
+
+    Example:
+
+        ::
+
+            def prof_on_message_stanza_receive(stanza: str) -> bool:
+                prof.cons_show(f"Received message stanza: {stanza}")
+                return True
     """
     pass
 
+def prof_on_presence_stanza_send(stanza: str) -> str | None:
+    """Called before an XMPP presence stanza is sent.
 
-def prof_on_presence_stanza_send(stanza):
+    Allows the plugin to modify or cancel the stanza.
-    """Called before an XMPP presence stanza is sent
 
-    :param stanza: The stanza to send
+    Args:
-    :type stanza: str or unicode
+        stanza: The XMPP presence stanza to send.
-    :return: The new stanza to send, or ``None`` to preserve the original stanza
+
-    :rtype: str or unicode
+    Returns:
+        str | None: The modified stanza to send, or None to preserve the original.
+
+    Example:
+
+        ::
+
+            def prof_on_presence_stanza_send(stanza: str) -> str | None:
+                prof.cons_show(f"Sending presence stanza: {stanza}")
+                return stanza
     """
     pass
 
+def prof_on_presence_stanza_receive(stanza: str) -> bool:
+    """Called when an XMPP presence stanza is received.
 
-def prof_on_presence_stanza_receive(stanza):
+    Allows the plugin to control whether CProof processes the stanza.
-    """Called when an XMPP presence stanza is received
 
-    :param stanza: The stanza received
+    Args:
-    :type stanza: str or unicode
+        stanza: The received XMPP presence stanza.
-    :return: ``True`` if Profanity should continue to process the presence stanza, ``False`` otherwise
+
-    :rtype: boolean
+    Returns:
+        bool: True to allow CProof to process the stanza, False to block processing.
+
+    Example:
+
+        ::
+
+            def prof_on_presence_stanza_receive(stanza: str) -> bool:
+                prof.cons_show(f"Received presence stanza: {stanza}")
+                return True
     """
     pass
 
+def prof_on_iq_stanza_send(stanza: str) -> str | None:
+    """Called before an XMPP IQ stanza is sent.
 
-def prof_on_iq_stanza_send(stanza):
+    Allows the plugin to modify or cancel the stanza.
-    """Called before an XMPP iq stanza is sent
 
-    :param stanza: The stanza to send
+    Args:
-    :type stanza: str or unicode
+        stanza: The XMPP IQ stanza to send.
-    :return: The new stanza to send, or ``None`` to preserve the original stanza
+
-    :rtype: str or unicode
+    Returns:
+        str | None: The modified stanza to send, or None to preserve the original.
+
+    Example:
+
+        ::
+
+            def prof_on_iq_stanza_send(stanza: str) -> str | None:
+                prof.cons_show(f"Sending IQ stanza: {stanza}")
+                return stanza
     """
     pass
 
+def prof_on_iq_stanza_receive(stanza: str) -> bool:
+    """Called when an XMPP IQ stanza is received.
 
-def prof_on_iq_stanza_receive(stanza):
+    Allows the plugin to control whether CProof processes the stanza.
-    """Called when an XMPP iq stanza is received
 
-    :param stanza: The stanza received
+    Args:
-    :type stanza: str or unicode
+        stanza: The received XMPP IQ stanza.
-    :return: ``True`` if Profanity should continue to process the iq stanza, ``False`` otherwise
+
-    :rtype: boolean
+    Returns:
+        bool: True to allow CProof to process the stanza, False to block processing.
+
+    Example:
+
+        ::
+
+            def prof_on_iq_stanza_receive(stanza: str) -> bool:
+                prof.cons_show(f"Received IQ stanza: {stanza}")
+                return True
     """
     pass
 
+# Contact Presence Handlers
+# -------------------------
 
-def prof_on_contact_offline(barejid, resource, status):
+def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
-    """Called when a contact goes offline
+    """Called when a contact goes offline.
 
-    :param barejid: Jabber ID of the contact
+    Args:
-    :param resource: the resource being disconnected
+        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
-    :param status: the status message received with the offline presence, or ``None``
+        resource: The resource being disconnected (e.g., ``laptop``).
-    :type barejid: str or unicode
+        status: The status message received with the offline presence, or None.
-    :type resource: str or unicode
+
-    :type status: str or unicode
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None:
+                prof.cons_show(f"{barejid}/{resource} went offline: {status or 'No status'}")
     """
     pass
 
+def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
+    """Called when a presence notification is received from a contact.
 
-def prof_on_contact_presence(barejid, resource, presence, status, priority):
+    Args:
-    """Called when a presence notification is received from a contact
+        barejid: The Jabber ID of the contact (e.g., ``bob@example.com``).
+        resource: The resource of the contact (e.g., ``laptop``).
+        presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``).
+        status: The status message received with the presence, or None.
+        priority: The priority associated with the resource.
 
-    :param barejid: Jabber ID of the contact
+    Returns:
-    :param resource: the resource being disconnected
+        None
-    :param presence: presence of the contact, one of ``"chat"``, ``"online"``, ``"away"``, ``"xa"`` or ``"dnd"``
+
-    :param status: the status message received with the presence, or ``None``
+    Example:
-    :param priority: the priority associated with the resource
+
-    :type barejid: str or unicode
+        ::
-    :type resource: str or unicode
+
-    :type presence: str or unicode
+            def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None:
-    :type status: str or unicode
+                prof.notify(f"{barejid} is {presence}", 5000, "Presence")
-    :type priority: int
     """
     pass
 
+# Window Focus Handlers
+# ---------------------
 
-def prof_on_chat_win_focus(barejid):
+def prof_on_chat_win_focus(barejid: str) -> None:
-    """Called when a chat window is focused
+    """Called when a chat window is focused.
 
-    :param barejid: Jabber ID of the chat window recipient
+    Args:
-    :type barejid: str or unicode
+        barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``).
+
+    Returns:
+        None
+
+    Example:
+
+        ::
+
+            def prof_on_chat_win_focus(barejid: str) -> None:
+                prof.cons_show(f"Focused chat window for {barejid}")
     """
     pass
 
+def prof_on_room_win_focus(barejid: str) -> None:
+    """Called when a chat room window is focused.
 
-def prof_on_room_win_focus(barejid):
+    Args:
-    """Called when a chat room window is focused
+        barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``).
 
-    :param barejid: Jabber ID of the room
+    Returns:
-    :type barejid: str or unicode
+        None
+
+    Example:
+
+        ::
+
+            def prof_on_room_win_focus(barejid: str) -> None:
+                prof.cons_show(f"Focused room window for {barejid}")
     """
     pass