From c94263486f69111d904864538c9cd8b02c2bdc5a Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Wed, 17 Sep 2025 00:34:37 +0200 Subject: [PATCH 1/5] docs(python): fix formatting to ensure correct parsing Fixes issues introduced in 052e168, 4cdcf9a, and other commits from PR #31. --- apidocs/python/src/plugin.py | 340 ++++-------- apidocs/python/src/prof.py | 964 +++++++++++++---------------------- 2 files changed, 441 insertions(+), 863 deletions(-) diff --git a/apidocs/python/src/plugin.py b/apidocs/python/src/plugin.py index 59f07328..b393622a 100644 --- a/apidocs/python/src/plugin.py +++ b/apidocs/python/src/plugin.py @@ -3,12 +3,14 @@ The plugin module defines optional callback functions that CProof plugins can implement to handle events such as startup, shutdown, message processing, and presence updates. -:: - - import prof - All functions are optional and are called by CProof when the corresponding event -occurs. String parameters and return values are Python 3 str types. +occurs. You need to define them in your module and they will automatically be used +for callback events. + +To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof`` +documentation and use: + :: + import prof """ # Initialization and Lifecycle @@ -20,19 +22,14 @@ def prof_init(version: str, status: str, account_name: str | None, fulljid: str Called when CProof starts or when the plugin is loaded via the ``/plugins load`` or ``/plugins install`` commands. - Args: - 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 + :param version: The version of CProof (e.g., ``"1.0.0"``). + :param status: The package status of CProof (``"development"`` or ``"release"``). + :param account_name: The account name of the logged-in user, or None if not logged in. + :param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in. + :return: 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}") """ @@ -43,16 +40,10 @@ def prof_on_start() -> None: Use this to perform setup tasks that should occur at application startup. - Args: - None - - Returns: - None + :return: None Example: - :: - def prof_on_start() -> None: prof.cons_show("CProof has started...") """ @@ -63,16 +54,10 @@ def prof_on_shutdown() -> None: Use this to perform cleanup tasks before the application exits. - Args: - None - - Returns: - None + :return: None Example: - :: - def prof_on_shutdown() -> None: prof.cons_show("CProof is shutting down...") """ @@ -83,16 +68,10 @@ def prof_on_unload() -> None: Use this to clean up plugin-specific resources. - Args: - None - - Returns: - None + :return: None Example: - :: - def prof_on_unload() -> None: prof.cons_show("Plugin unloaded") """ @@ -101,17 +80,12 @@ def prof_on_unload() -> None: def prof_on_connect(account_name: str, fulljid: str) -> None: """Called when a user connects to CProof with an account. - Args: - account_name: The account name used for login. - fulljid: The full Jabber ID (barejid/resource) of the connected account. - - Returns: - None + :param account_name: The account name used for login. + :param fulljid: The full Jabber ID (barejid/resource) of the connected account. + :return: None Example: - :: - def prof_on_connect(account_name: str, fulljid: str) -> None: prof.cons_show(f"Connected as {account_name} ({fulljid})") """ @@ -120,17 +94,12 @@ def prof_on_connect(account_name: str, fulljid: str) -> None: def prof_on_disconnect(account_name: str, fulljid: str) -> None: """Called when a user disconnects an account from CProof. - Args: - account_name: The account name being disconnected. - fulljid: The full Jabber ID (barejid/resource) of the disconnected account. - - Returns: - None + :param account_name: The account name being disconnected. + :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account. + :return: None Example: - :: - def prof_on_disconnect(account_name: str, fulljid: str) -> None: prof.cons_show(f"Disconnected {account_name} ({fulljid})") """ @@ -144,18 +113,13 @@ def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> Allows the plugin to modify or cancel the message display. - Args: - barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). - resource: The sender's resource (e.g., ``laptop``). - message: The received message. - - Returns: - str | None: The modified message to display, or None to preserve the original. + :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). + :param resource: The sender's resource (e.g., ``laptop``). + :param message: The received message. + :return: 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 @@ -167,18 +131,13 @@ def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> Use this to perform actions after the message is shown. - Args: - barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). - resource: The sender's resource (e.g., ``laptop``). - message: The displayed message. - - Returns: - None + :param barejid: The Jabber ID of the message sender (e.g., ``bob@example.com``). + :param resource: The sender's resource (e.g., ``laptop``). + :param message: The displayed message. + :return: 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}") """ @@ -189,17 +148,12 @@ def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: Allows the plugin to modify or cancel the message. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - message: The message to be sent. - - Returns: - str | None: The modified message to send, or None to cancel sending. + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param message: The message to be sent. + :return: 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)" """ @@ -210,17 +164,12 @@ def prof_post_chat_message_send(barejid: str, message: str) -> None: Use this to log or react to sent messages. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - message: The sent message. - - Returns: - None + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param message: The sent message. + :return: None Example: - :: - def prof_post_chat_message_send(barejid: str, message: str) -> None: prof.cons_show(f"Sent to {barejid}: {message}") """ @@ -234,18 +183,13 @@ def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str Allows the plugin to modify or cancel the message display. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The received message. - - Returns: - str | None: The modified message to display, or None to preserve the original. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The received message. + :return: 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})" """ @@ -256,18 +200,13 @@ def prof_post_room_message_display(barejid: str, nick: str, message: str) -> Non Use this to perform actions after the message is shown. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The displayed message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The displayed message. + :return: 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}") """ @@ -278,17 +217,12 @@ def prof_pre_room_message_send(barejid: str, message: str) -> str | None: Allows the plugin to modify or cancel the message. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - message: The message to be sent. - - Returns: - str | None: The modified message to send, or None to cancel sending. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param message: The message to be sent. + :return: 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)" """ @@ -299,17 +233,12 @@ def prof_post_room_message_send(barejid: str, message: str) -> None: Use this to log or react to sent messages. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - message: The sent message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param message: The sent message. + :return: None Example: - :: - def prof_post_room_message_send(barejid: str, message: str) -> None: prof.cons_show(f"Sent to {barejid}: {message}") """ @@ -318,19 +247,14 @@ def prof_post_room_message_send(barejid: str, message: str) -> None: 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. - Args: - 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``). - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The received message. + :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``). + :return: None Example: - :: - 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}") """ @@ -344,18 +268,13 @@ def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str Allows the plugin to modify or cancel the message display. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The received message. - - Returns: - str | None: The modified message to display, or None to preserve the original. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The received message. + :return: 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})" """ @@ -366,18 +285,13 @@ def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> Non Use this to perform actions after the message is shown. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message sender. - message: The displayed message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message sender. + :param message: The displayed message. + :return: 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}") """ @@ -388,18 +302,13 @@ def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | N Allows the plugin to modify or cancel the message. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message recipient. - message: The message to be sent. - - Returns: - str | None: The modified message to send, or None to cancel sending. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message recipient. + :param message: The message to be sent. + :return: The modified message to send, or None to cancel sending. Example: - :: - def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: return f"{message} (private to {nick})" """ @@ -410,18 +319,13 @@ def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: Use this to log or react to sent messages. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - nick: The nickname of the message recipient. - message: The sent message. - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param nick: The nickname of the message recipient. + :param message: The sent message. + :return: 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}") """ @@ -435,16 +339,11 @@ def prof_on_message_stanza_send(stanza: str) -> str | None: Allows the plugin to modify or cancel the stanza. - Args: - stanza: The XMPP message stanza to send. - - Returns: - str | None: The modified stanza to send, or None to preserve the original. + :param stanza: The XMPP message stanza to send. + :return: 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 @@ -456,16 +355,11 @@ def prof_on_message_stanza_receive(stanza: str) -> bool: Allows the plugin to control whether CProof processes the stanza. - Args: - stanza: The received XMPP message stanza. - - Returns: - bool: True to allow CProof to process the stanza, False to block processing. + :param stanza: The received XMPP message stanza. + :return: 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 @@ -477,16 +371,11 @@ def prof_on_presence_stanza_send(stanza: str) -> str | None: Allows the plugin to modify or cancel the stanza. - Args: - stanza: The XMPP presence stanza to send. - - Returns: - str | None: The modified stanza to send, or None to preserve the original. + :param stanza: The XMPP presence stanza to send. + :return: 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 @@ -498,16 +387,11 @@ def prof_on_presence_stanza_receive(stanza: str) -> bool: Allows the plugin to control whether CProof processes the stanza. - Args: - stanza: The received XMPP presence stanza. - - Returns: - bool: True to allow CProof to process the stanza, False to block processing. + :param stanza: The received XMPP presence stanza. + :return: 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 @@ -519,16 +403,11 @@ def prof_on_iq_stanza_send(stanza: str) -> str | None: Allows the plugin to modify or cancel the stanza. - Args: - stanza: The XMPP IQ stanza to send. - - Returns: - str | None: The modified stanza to send, or None to preserve the original. + :param stanza: The XMPP IQ stanza to send. + :return: 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 @@ -540,16 +419,11 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool: Allows the plugin to control whether CProof processes the stanza. - Args: - stanza: The received XMPP IQ stanza. - - Returns: - bool: True to allow CProof to process the stanza, False to block processing. + :param stanza: The received XMPP IQ stanza. + :return: 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 @@ -562,18 +436,13 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool: def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> None: """Called when a contact goes offline. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - resource: The resource being disconnected (e.g., ``laptop``). - status: The status message received with the offline presence, or None. - - Returns: - None + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param resource: The resource being disconnected (e.g., ``laptop``). + :param status: The status message received with the offline presence, or None. + :return: 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'}") """ @@ -582,20 +451,15 @@ def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> 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. - Args: - 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. - - Returns: - None + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param resource: The resource of the contact (e.g., ``laptop``). + :param presence: The contact's presence (``"chat"``, ``"online"``, ``"away"``, ``"xa"``, or ``"dnd"``). + :param status: The status message received with the presence, or None. + :param priority: The priority associated with the resource. + :return: None Example: - :: - def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None: prof.notify(f"{barejid} is {presence}", 5000, "Presence") """ @@ -607,16 +471,11 @@ def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: def prof_on_chat_win_focus(barejid: str) -> None: """Called when a chat window is focused. - Args: - barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). - - Returns: - None + :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). + :return: None Example: - :: - def prof_on_chat_win_focus(barejid: str) -> None: prof.cons_show(f"Focused chat window for {barejid}") """ @@ -625,17 +484,12 @@ def prof_on_chat_win_focus(barejid: str) -> None: def prof_on_room_win_focus(barejid: str) -> None: """Called when a chat room window is focused. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - None + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :return: None Example: - :: - def prof_on_room_win_focus(barejid: str) -> None: prof.cons_show(f"Focused room window for {barejid}") """ - pass + pass \ No newline at end of file diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index 1902faaf..d42168ee 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -3,27 +3,54 @@ The prof module provides a Python API for plugins to interact with CProof. Plugins must import this module to access its functions: :: - import prof 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.""" + """Protocol for command callbacks accepting variable string arguments. + + :param command_parameters: Variable string arguments passed to the callback. + :return: None + + Example: + :: + def my_command(*command_parameters: str) -> None: + prof.cons_show(f"Received: {command_parameters}") + """ def __call__(self, *command_parameters: str) -> None: ... class TimedCallback(Protocol): - """Protocol for timed callbacks accepting no arguments.""" + """Protocol for timed callbacks accepting no arguments. + + :return: None + + Example: + :: + def my_timed_callback() -> None: + prof.cons_show("Timer triggered") + """ def __call__(self) -> None: ... class WindowCallback(Protocol): - """Protocol for window callbacks accepting a window ID and message.""" + """Protocol for window callbacks accepting a window ID and message. + + :param win_id: The window tag identifying the plugin window. + :param message: The message to process. + :return: None + + Example: + :: + def my_window_callback(win_id: str, message: str) -> None: + prof.win_show(win_id, f"Processed: {message}") + """ def __call__(self, win_id: str, message: str) -> None: ... # Console Functions @@ -32,34 +59,23 @@ class WindowCallback(Protocol): def cons_alert() -> None: """Highlights the console window in the CProof status bar to indicate activity. - Args: - None - - Returns: - None + :return: None Example: - - :: - - prof.cons_alert() # Highlights the console window + :: + prof.cons_alert() # Highlights the console window """ pass def cons_show(message: str) -> None: """Displays a message in the CProof console window. - Args: - message: The message to display. - - Returns: - None + :param message: The message to display. + :return: None Example: - - :: - - prof.cons_show("This appears in the console window") + :: + prof.cons_show("This appears in the console window") """ pass @@ -69,37 +85,27 @@ def cons_show_themed(group: str | None, key: str | None, default: str | None, me Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - message: The message to display. - - Returns: - None + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param message: The message to display. + :return: None Example: - - :: - - prof.cons_show_themed("myplugin", "text", "white", "Themed message") + :: + prof.cons_show_themed("myplugin", "text", "white", "Themed message") """ pass def cons_bad_cmd_usage(command: str) -> None: """Displays an error message in the console for incorrect command usage. - Args: - command: The command name, including the leading slash (e.g., ``/say``). - - Returns: - None + :param command: The command name, including the leading slash (e.g., ``/say``). + :return: None Example: - - :: - - prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand + :: + prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand """ pass @@ -122,42 +128,37 @@ def register_command( the command is invoked. The callback function accepts variable string arguments representing the command parameters. - Args: - name: The command name, including the leading slash (e.g., ``/say``). - min_args: Minimum number of arguments required. - max_args: Maximum number of arguments allowed. - synopsis: List of command usage strings. - 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 variable string arguments. - - Returns: - None + :param name: The command name, including the leading slash (e.g., ``/say``). + :param min_args: Minimum number of arguments required. + :param max_args: Maximum number of arguments allowed. + :param synopsis: List of command usage strings. + :param description: Short description of the command. + :param arguments: List of [argument, description] pairs for help text. + :param examples: List of example command invocations. + :param callback: Function to call when the command is executed, taking variable string arguments. + :return: None Example: + :: + 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") - :: - - 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 = ["/new_command on|off", "/new_command print "] - description = "Enables, disables, or prints an argument." - arguments = [ - ["on|off", "Enable or disable something."], - ["print ", "Print the argument."] - ] - examples = ["/new_command on", "/new_command print 'test'"] - prof.register_command( - "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler - ) + synopsis = ["/new_command on|off", "/new_command print "] + description = "Enables, disables, or prints an argument." + arguments = [ + ["on|off", "Enable or disable something."], + ["print ", "Print the argument."] + ] + examples = ["/new_command on", "/new_command print 'test'"] + prof.register_command( + "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler + ) """ pass @@ -167,21 +168,16 @@ def register_command( def register_timed(callback: TimedCallback, interval: int) -> None: """Registers a function to be called periodically by CProof. - Args: - callback: The function to call periodically. - interval: The time between calls, in seconds. - - Returns: - None + :param callback: The function to call periodically. + :param interval: The time between calls, in seconds. + :return: None Example: + :: + def periodic_task() -> None: + prof.cons_show("Periodic update") - :: - - def periodic_task() -> None: - prof.cons_show("Periodic update") - - prof.register_timed(periodic_task, 30) # Calls every 30 seconds + prof.register_timed(periodic_task, 30) # Calls every 30 seconds """ pass @@ -194,71 +190,51 @@ def completer_add(key: str, items: list[str]) -> None: If the key already exists, the items are appended to the existing autocomplete list. - Args: - key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``). - items: The items to return on autocompletion. - - Returns: - None + :param key: The prefix to trigger autocompletion (e.g., ``/mycommand`` or ``/mycommand action``). + :param items: The items to return on autocompletion. + :return: None Example: - - :: - - prof.completer_add("/mycommand", ["action1", "action2"]) - prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) + :: + prof.completer_add("/mycommand", ["action1", "action2"]) + prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) """ pass def completer_remove(key: str, items: list[str]) -> None: """Removes values from autocompletion for a command or command argument. - Args: - key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``). - items: The items to remove from the autocomplete list. - - Returns: - None + :param key: The prefix from which to remove autocomplete items (e.g., ``/mycommand``). + :param items: The items to remove from the autocomplete list. + :return: None Example: - - :: - - prof.completer_remove("/mycommand", ["action1", "action2"]) + :: + prof.completer_remove("/mycommand", ["action1", "action2"]) """ pass def completer_clear(key: str) -> None: """Clears all autocomplete values for a command or command argument. - Args: - key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). - - Returns: - None + :param key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). + :return: None Example: - - :: - - prof.completer_clear("/mycommand") + :: + prof.completer_clear("/mycommand") """ pass def filepath_completer_add(prefix: str) -> None: """Enables filepath autocompletion for a command or command argument. - Args: - prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). - - Returns: - None + :param prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). + :return: None Example: - - :: - - prof.filepath_completer_add("/filecmd") # Enables filepath completion + :: + prof.filepath_completer_add("/filecmd") # Enables filepath completion """ pass @@ -268,18 +244,13 @@ def filepath_completer_add(prefix: str) -> None: def win_exists(tag: str) -> bool: """Checks if a plugin window with the specified tag exists. - Args: - tag: The tag identifying the plugin window. - - Returns: - bool: True if the window exists, False otherwise. + :param tag: The tag identifying the plugin window. + :return: True if the window exists, False otherwise. Example: - - :: - - if prof.win_exists("MyPlugin"): - prof.cons_show("Window exists") + :: + if prof.win_exists("MyPlugin"): + prof.cons_show("Window exists") """ pass @@ -289,56 +260,41 @@ def win_create(tag: str, callback: WindowCallback) -> None: The callback processes input messages, typically using the model from the window title, and is called with the window tag and message. - Args: - tag: The tag identifying the plugin window. - callback: Function to process window input, taking the window tag and message. - - Returns: - None + :param tag: The tag identifying the plugin window. + :param callback: Function to process window input, taking the window tag and message. + :return: None Example: + :: + def handler(win_id: str, message: str) -> None: + prof.win_show(win_id, f"Processed: {message}") - :: - - def handler(win_id: str, message: str) -> None: - prof.win_show(win_id, f"Processed: {message}") - - prof.win_create("MyPlugin", handler) + prof.win_create("MyPlugin", handler) """ pass def win_focus(tag: str) -> None: """Focuses the plugin window with the specified tag. - Args: - tag: The tag identifying the plugin window. - - Returns: - None + :param tag: The tag identifying the plugin window. + :return: None Example: - - :: - - prof.win_focus("MyPlugin") # Focuses the MyPlugin window + :: + prof.win_focus("MyPlugin") # Focuses the MyPlugin window """ pass def win_show(tag: str, message: str) -> None: """Displays a message in the plugin window with the specified tag. - Args: - tag: The tag identifying the plugin window. - message: The message to display. - - Returns: - None + :param tag: The tag identifying the plugin window. + :param message: The message to display. + :return: None Example: - - :: - - prof.win_show("MyPlugin", "Message in plugin window") + :: + prof.win_show("MyPlugin", "Message in plugin window") """ pass @@ -348,21 +304,16 @@ def win_show_themed(tag: str, group: str | None, key: str | None, default: str | Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - tag: The tag identifying the plugin window. - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - message: The message to display. - - Returns: - None + :param tag: The tag identifying the plugin window. + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param message: The message to display. + :return: None Example: - - :: - - prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") + :: + prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") """ pass @@ -372,20 +323,14 @@ def win_show_themed(tag: str, group: str | None, key: str | None, default: str | def chat_show(barejid: str, message: str) -> bool: """Displays a message in the chat window for the specified contact. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the chat window does not - exist. + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param message: The message to display. + :return: True if the message was displayed, False if the chat window does not exist. Example: - - :: - - if prof.chat_show("bob@example.com", "Hello from plugin"): - prof.cons_show("Message displayed") + :: + if prof.chat_show("bob@example.com", "Hello from plugin"): + prof.cons_show("Message displayed") """ pass @@ -402,42 +347,30 @@ def chat_show_themed( Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - ch: The prefix character to display, or None for default behavior. - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the chat window does not - exist. + :param barejid: The Jabber ID of the recipient (e.g., ``bob@example.com``). + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param ch: The prefix character to display, or None for default behavior. + :param message: The message to display. + :return: True if the message was displayed, False if the chat window does not exist. Example: - - :: - - prof.chat_show_themed("bob@example.com", "myplugin", "text", None, "!", "Themed message") + :: + prof.chat_show_themed("bob@example.com", "myplugin", "text", None, "!", "Themed message") """ pass def room_show(roomjid: str, message: str) -> bool: """Displays a message in the chat room window for the specified room. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the room window does not - exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param message: The message to display. + :return: True if the message was displayed, False if the room window does not exist. Example: - - :: - - prof.room_show("chat@conference.example.com", "Room message from plugin") + :: + prof.room_show("chat@conference.example.com", "Room message from plugin") """ pass @@ -454,23 +387,17 @@ def room_show_themed( Themes are defined in ``~/.local/share/cproof/plugin_themes``. If the theme is not found, the default color is used. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - group: The theme group name, or None to use default styling. - key: The item name within the group, or None to use default styling. - default: The default color if the theme is not found, or None for no color. - ch: The prefix character to display, or None for default behavior. - message: The message to display. - - Returns: - bool: True if the message was displayed, False if the room window does not - exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param group: The theme group name, or None to use default styling. + :param key: The item name within the group, or None to use default styling. + :param default: The default color if the theme is not found, or None for no color. + :param ch: The prefix character to display, or None for default behavior. + :param message: The message to display. + :return: True if the message was displayed, False if the room window does not exist. Example: - - :: - - prof.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message") + :: + prof.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message") """ pass @@ -480,16 +407,11 @@ def room_show_themed( def send_line(line: str) -> None: """Sends a line of input to CProof for execution, as if typed by the user. - Args: - line: The input line to execute (e.g., ``/who online``). - - Returns: - None + :param line: The input line to execute (e.g., ``/who online``). + :return: None Example: - :: - prof.send_line("/who online") # Executes the /who online command """ pass @@ -497,39 +419,28 @@ def send_line(line: str) -> None: def send_stanza(stanza: str) -> bool: """Sends an XMPP stanza to the server. - Args: - stanza: The XMPP stanza to send (e.g., an IQ or message stanza). - - Returns: - bool: True if the stanza was sent successfully, False if it was invalid or - failed to send. + :param stanza: The XMPP stanza to send (e.g., an IQ or message stanza). + :return: True if the stanza was sent successfully, False if it was invalid or failed to send. Example: - - :: - - stanza = "" - if prof.send_stanza(stanza): - prof.cons_show("Stanza sent successfully") + :: + stanza = "" + if prof.send_stanza(stanza): + prof.cons_show("Stanza sent successfully") """ pass def incoming_message(barejid: str, resource: str, message: str) -> None: """Triggers CProof to handle an incoming message as if received from a contact. - Args: - barejid: The Jabber ID of the sender (e.g., ``bob@example.com``). - resource: The sender's resource (e.g., ``laptop``). - message: The message text. - - Returns: - None + :param barejid: The Jabber ID of the sender (e.g., ``bob@example.com``). + :param resource: The sender's resource (e.g., ``laptop``). + :param message: The message text. + :return: None Example: - - :: - - prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") + :: + prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") """ pass @@ -539,52 +450,37 @@ def disco_add_feature(feature: str) -> None: If a session is active, a presence update is sent to refresh client/server feature caches. - Args: - feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). - - Returns: - None + :param feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). + :return: None Example: - - :: - - prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") + :: + prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") """ pass def encryption_reset(barejid: str) -> None: """Ends any encrypted session with the specified contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). - - Returns: - None + :param barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). + :return: None Example: - - :: - - prof.encryption_reset("alice@example.com") # Resets encryption + :: + prof.encryption_reset("alice@example.com") # Resets encryption """ pass def chat_set_titlebar_enctext(barejid: str, enctext: str) -> bool: """Sets the encryption indicator text in the titlebar for a contact's chat window. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - enctext: The text to display in the titlebar. - - Returns: - bool: True if the text was set, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param enctext: The text to display in the titlebar. + :return: True if the text was set, False if the chat window does not exist. Example: - - :: - - prof.chat_set_titlebar_enctext("bob@example.com", "secure") + :: + prof.chat_set_titlebar_enctext("bob@example.com", "secure") """ pass @@ -593,34 +489,24 @@ def chat_unset_titlebar_enctext(barejid: str) -> bool: CProof will determine the default text to display. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - - Returns: - bool: True if the text was reset, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :return: True if the text was reset, False if the chat window does not exist. Example: - - :: - - prof.chat_unset_titlebar_enctext("bob@example.com") + :: + prof.chat_unset_titlebar_enctext("bob@example.com") """ pass def chat_set_incoming_char(barejid: str, ch: str) -> bool: """Sets the prefix character for incoming messages from a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - ch: The prefix character to display. - - Returns: - bool: True if the character was set, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param ch: The prefix character to display. + :return: True if the character was set, False if the chat window does not exist. Example: - :: - prof.chat_set_incoming_char("bob@example.com", "*") """ pass @@ -628,70 +514,50 @@ def chat_set_incoming_char(barejid: str, ch: str) -> bool: def chat_unset_incoming_char(barejid: str) -> bool: """Resets the prefix character for incoming messages from a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - - Returns: - bool: True if the character was reset, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :return: True if the character was reset, False if the chat window does not exist. Example: - - :: - - prof.chat_unset_incoming_char("bob@example.com") + :: + prof.chat_unset_incoming_char("bob@example.com") """ pass def chat_set_outgoing_char(barejid: str, ch: str) -> bool: """Sets the prefix character for outgoing messages to a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - ch: The prefix character to display. - - Returns: - bool: True if the character was set, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :param ch: The prefix character to display. + :return: True if the character was set, False if the chat window does not exist. Example: - - :: - - prof.chat_set_outgoing_char("bob@example.com", "+") + :: + prof.chat_set_outgoing_char("bob@example.com", "+") """ pass def chat_unset_outgoing_char(barejid: str) -> bool: """Resets the prefix character for outgoing messages to a contact. - Args: - barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). - - Returns: - bool: True if the character was reset, False if the chat window does not exist. + :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). + :return: True if the character was reset, False if the chat window does not exist. Example: - - :: - - prof.chat_unset_outgoing_char("bob@example.com") + :: + prof.chat_unset_outgoing_char("bob@example.com") """ pass def room_set_titlebar_enctext(roomjid: str, enctext: str) -> bool: """Sets the encryption indicator text in the titlebar for a room's chat window. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - enctext: The text to display in the titlebar. - - Returns: - bool: True if the text was set, False if the room window does not exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param enctext: The text to display in the titlebar. + :return: True if the text was set, False if the room window does not exist. Example: - - :: - - prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") + :: + prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") """ pass @@ -700,52 +566,37 @@ def room_unset_titlebar_enctext(roomjid: str) -> bool: CProof will determine the default text to display. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - bool: True if the text was reset, False if the room window does not exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :return: True if the text was reset, False if the room window does not exist. Example: - - :: - - prof.room_unset_titlebar_enctext("chat@conference.example.com") + :: + prof.room_unset_titlebar_enctext("chat@conference.example.com") """ pass def room_set_message_char(roomjid: str, ch: str) -> bool: """Sets the prefix character for messages in a chat room. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - ch: The prefix character to display. - - Returns: - bool: True if the character was set, False if the room window does not exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :param ch: The prefix character to display. + :return: True if the character was set, False if the room window does not exist. Example: - - :: - - prof.room_set_message_char("chat@conference.example.com", "^") + :: + prof.room_set_message_char("chat@conference.example.com", "^") """ pass def room_unset_message_char(roomjid: str) -> bool: """Resets the prefix character for messages in a chat room. - Args: - roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - bool: True if the character was reset, False if the room window does not exist. + :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :return: True if the character was reset, False if the room window does not exist. Example: - - :: - - prof.room_unset_message_char("chat@conference.example.com") + :: + prof.room_unset_message_char("chat@conference.example.com") """ pass @@ -757,19 +608,14 @@ def settings_boolean_get(group: str, key: str, default: bool) -> bool: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - default: The default value if the setting is not found. - - Returns: - bool: The setting value, or the default if not found. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param default: The default value if the setting is not found. + :return: The setting value, or the default if not found. Example: - - :: - - notify = prof.settings_boolean_get("myplugin", "notify", False) + :: + notify = prof.settings_boolean_get("myplugin", "notify", False) """ pass @@ -778,18 +624,13 @@ def settings_boolean_set(group: str, key: str, value: bool) -> None: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The boolean value to set. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The boolean value to set. + :return: None Example: - :: - prof.settings_boolean_set("myplugin", "notify", True) """ pass @@ -799,19 +640,14 @@ def settings_string_get(group: str, key: str, default: str) -> str: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - default: The default value if the setting is not found. - - Returns: - str: The setting value, or the default if not found. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param default: The default value if the setting is not found. + :return: The setting value, or the default if not found. Example: - - :: - - prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") + :: + prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") """ pass @@ -820,19 +656,14 @@ def settings_string_set(group: str, key: str, value: str) -> None: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The string value to set. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The string value to set. + :return: None Example: - - :: - - prof.settings_string_set("myplugin", "prefix", "myplugin>") + :: + prof.settings_string_set("myplugin", "prefix", "myplugin>") """ pass @@ -842,19 +673,13 @@ def settings_string_list_get(group: str, key: str) -> list[str]: Settings are stored in ``~/.local/share/cproof/plugin_settings``, with list items separated by semicolons. - Args: - group: The group name in the settings file. - key: The item name within the group. - - Returns: - list[str]: The list of strings, or an empty list if the setting does not - exist. + :param group: The group name in the settings file. + :param key: The item name within the group. + :return: List of strings, or an empty list if the setting does not exist. Example: - - :: - - items = prof.settings_string_list_get("myplugin", "items") + :: + items = prof.settings_string_list_get("myplugin", "items") """ pass @@ -864,19 +689,14 @@ def settings_string_list_add(group: str, key: str, value: str) -> None: If the list does not exist, it is created with the new item. Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The string to add to the list. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The string to add to the list. + :return: None Example: - - :: - - prof.settings_string_list_add("myplugin", "items", "item1") + :: + prof.settings_string_list_add("myplugin", "items", "item1") """ pass @@ -885,20 +705,14 @@ def settings_string_list_remove(group: str, key: str, value: str) -> bool: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The string to remove from the list. - - Returns: - bool: True if the item was removed or not in the list, False if the list - does not exist. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The string to remove from the list. + :return: True if the item was removed or not in the list, False if the list does not exist. Example: - - :: - - prof.settings_string_list_remove("myplugin", "items", "item1") + :: + prof.settings_string_list_remove("myplugin", "items", "item1") """ pass @@ -907,18 +721,13 @@ def settings_string_list_clear(group: str, key: str) -> bool: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - - Returns: - bool: True if the list was cleared, False if the list does not exist. + :param group: The group name in the settings file. + :param key: The item name within the group. + :return: True if the list was cleared, False if the list does not exist. Example: - - :: - - prof.settings_string_list_clear("myplugin", "items") + :: + prof.settings_string_list_clear("myplugin", "items") """ pass @@ -927,19 +736,14 @@ def settings_int_get(group: str, key: str, default: int) -> int: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - default: The default value if the setting is not found. - - Returns: - int: The setting value, or the default if not found. + :param group: The group name in the settings file. + :param key: The item name within the group. + :param default: The default value if the setting is not found. + :return: The setting value, or the default if not found. Example: - - :: - - timeout = prof.settings_int_get("myplugin", "timeout", 10) + :: + timeout = prof.settings_int_get("myplugin", "timeout", 10) """ pass @@ -948,19 +752,14 @@ def settings_int_set(group: str, key: str, value: int) -> None: Settings are stored in ``~/.local/share/cproof/plugin_settings``. - Args: - group: The group name in the settings file. - key: The item name within the group. - value: The integer value to set. - - Returns: - None + :param group: The group name in the settings file. + :param key: The item name within the group. + :param value: The integer value to set. + :return: None Example: - - :: - - prof.settings_int_set("myplugin", "timeout", 100) + :: + prof.settings_int_set("myplugin", "timeout", 100) """ pass @@ -970,153 +769,103 @@ def settings_int_set(group: str, key: str, value: int) -> None: def get_current_recipient() -> str | None: """Retrieves the Jabber ID of the current chat recipient. - Args: - None - - Returns: - str | None: The Jabber ID of the recipient (e.g., ``bob@example.com``), or - None if not in a chat window. + :return: The Jabber ID of the recipient (e.g., ``bob@example.com``), or None if not in a chat window. Example: - - :: - - recipient = prof.get_current_recipient() - if recipient: - prof.cons_show(f"Chatting with: {recipient}") + :: + recipient = prof.get_current_recipient() + if recipient: + prof.cons_show(f"Chatting with: {recipient}") """ pass def get_current_muc() -> str | None: """Retrieves the Jabber ID of the current chat room. - Args: - None - - Returns: - str | None: The Jabber ID of the room (e.g., ``chat@conference.example.com``), - or None if not in a chat room window. + :return: The Jabber ID of the room (e.g., ``chat@conference.example.com``), or None if not in a chat room window. Example: - - :: - - room = prof.get_current_muc() - if room: - prof.cons_show(f"In room: {room}") + :: + room = prof.get_current_muc() + if room: + prof.cons_show(f"In room: {room}") """ pass def get_current_nick() -> str | None: """Retrieves the user's nickname in the current chat room. - Args: - None - - Returns: - str | None: The user's nickname (e.g., ``alice``), or None if not in a chat - room window. + :return: The user's nickname (e.g., ``alice``), or None if not in a chat room window. Example: - - :: - - nick = prof.get_current_nick() - if nick: - prof.cons_show(f"Nickname: {nick}") + :: + nick = prof.get_current_nick() + if nick: + prof.cons_show(f"Nickname: {nick}") """ pass def get_name_from_roster(barejid: str) -> str: """Retrieves the nickname for a Jabber ID from the roster. - Args: - barejid: The Jabber ID to look up (e.g., ``bob@example.com``). - - Returns: - str: The nickname from the roster, or the input barejid if not found. + :param barejid: The Jabber ID to look up (e.g., ``bob@example.com``). + :return: The nickname from the roster, or the input barejid if not found. Example: - - :: - - name = prof.get_name_from_roster("bob@example.com") - prof.cons_show(f"Name: {name}") + :: + name = prof.get_name_from_roster("bob@example.com") + prof.cons_show(f"Name: {name}") """ pass def get_barejid_from_roster(name: str) -> str | None: """Retrieves the Jabber ID for a nickname from the roster. - Args: - name: The nickname to look up. - - Returns: - str | None: The Jabber ID (e.g., ``bob@example.com``), or None if the - nickname is not in the roster. + :param name: The nickname to look up. + :return: The Jabber ID (e.g., ``bob@example.com``), or None if the nickname is not in the roster. Example: - - :: - - jid = prof.get_barejid_from_roster("bob") - if jid: - prof.cons_show(f"JID: {jid}") + :: + jid = prof.get_barejid_from_roster("bob") + if jid: + prof.cons_show(f"JID: {jid}") """ pass def get_current_occupants() -> list[str]: """Retrieves the nicknames of all occupants in the current chat room. - Args: - None - - Returns: - list[str]: List of occupant nicknames, or an empty list if not in a chat - room window. + :return: List of occupant nicknames, or an empty list if not in a chat room window. Example: - - :: - - occupants = prof.get_current_occupants() - prof.cons_show(f"Occupants: {', '.join(occupants)}") + :: + occupants = prof.get_current_occupants() + prof.cons_show(f"Occupants: {', '.join(occupants)}") """ pass def get_room_nick(barejid: str) -> str: """Retrieves the user's nickname in the specified chat room. - Args: - barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). - - Returns: - str: The user's nickname in the room. + :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). + :return: The user's nickname in the room. Example: - - :: - - nick = prof.get_room_nick("chat@conference.example.com") - prof.cons_show(f"Room nick: {nick}") + :: + nick = prof.get_room_nick("chat@conference.example.com") + prof.cons_show(f"Room nick: {nick}") """ pass def current_win_is_console() -> bool: """Checks if the console window is currently focused. - Args: - None - - Returns: - bool: True if the console window is focused, False otherwise. + :return: True if the console window is focused, False otherwise. Example: - - :: - - if prof.current_win_is_console(): - prof.cons_show("Console is focused") + :: + if prof.current_win_is_console(): + prof.cons_show("Console is focused") """ pass @@ -1126,86 +875,61 @@ def current_win_is_console() -> bool: def notify(message: str, timeout: int, category: str) -> None: """Sends a desktop notification through CProof. - Args: - message: The notification message to display. - timeout: The duration before the notification disappears, in milliseconds. - category: The notification category, displayed with the message. - - Returns: - None + :param message: The notification message to display. + :param timeout: The duration before the notification disappears, in milliseconds. + :param category: The notification category, displayed with the message. + :return: None Example: - - :: - - prof.notify("New message received", 5000, "MyPlugin") + :: + prof.notify("New message received", 5000, "MyPlugin") """ pass def log_debug(message: str) -> None: """Logs a message to the CProof log at the DEBUG level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_debug("Debugging plugin initialization") + :: + prof.log_debug("Debugging plugin initialization") """ pass def log_info(message: str) -> None: """Logs a message to the CProof log at the INFO level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_info("Plugin started successfully") + :: + prof.log_info("Plugin started successfully") """ pass def log_warning(message: str) -> None: """Logs a message to the CProof log at the WARNING level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_warning("Configuration issue detected") + :: + prof.log_warning("Configuration issue detected") """ pass def log_error(message: str) -> None: """Logs a message to the CProof log at the ERROR level. - Args: - message: The message to log. - - Returns: - None + :param message: The message to log. + :return: None Example: - - :: - - prof.log_error("Failed to connect to server") + :: + prof.log_error("Failed to connect to server") """ - pass + pass \ No newline at end of file -- 2.49.1 From 9fd62e2304f40384bb84dcd71260641bdb0833c4 Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Wed, 17 Sep 2025 01:00:30 +0200 Subject: [PATCH 2/5] ci: restructure and optimize execution conditions - The code tests will ignore doc changes and vice versa. - The CI is split in 2 parts for clarity --- .github/workflows/ci-api-docs.yml | 44 +++++++++++++++++++++ .github/workflows/{main.yml => ci-code.yml} | 40 +++++-------------- 2 files changed, 54 insertions(+), 30 deletions(-) create mode 100644 .github/workflows/ci-api-docs.yml rename .github/workflows/{main.yml => ci-code.yml} (76%) diff --git a/.github/workflows/ci-api-docs.yml b/.github/workflows/ci-api-docs.yml new file mode 100644 index 00000000..5a44983c --- /dev/null +++ b/.github/workflows/ci-api-docs.yml @@ -0,0 +1,44 @@ +name: CI API Docs + +on: + push: + branches: [master] + paths: + - 'apidocs/**' + pull_request: + branches: [master] + paths: + - 'apidocs/**' + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + 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" diff --git a/.github/workflows/main.yml b/.github/workflows/ci-code.yml similarity index 76% rename from .github/workflows/main.yml rename to .github/workflows/ci-code.yml index e4015b0d..d2e714ff 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/ci-code.yml @@ -1,10 +1,18 @@ -name: CI +name: CI Code on: push: branches: [master] + paths-ignore: + - 'docs/**' + - 'apidocs/**' + - 'README.md' pull_request: branches: [master] + paths-ignore: + - 'docs/**' + - 'apidocs/**' + - 'README.md' concurrency: group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} @@ -83,38 +91,10 @@ jobs: continue-on-error: true steps: - uses: actions/checkout@v4 - - name: install dependencies + - name: Install dependencies run: | sudo apt update sudo apt install -y --no-install-recommends codespell - 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" -- 2.49.1 From 92cb93081011a97e80964b1394104fb885487547 Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Wed, 17 Sep 2025 01:02:46 +0200 Subject: [PATCH 3/5] docs: Fix indentation --- apidocs/python/src/plugin.py | 122 +++++++------- apidocs/python/src/prof.py | 310 +++++++++++++++++++++-------------- 2 files changed, 246 insertions(+), 186 deletions(-) diff --git a/apidocs/python/src/plugin.py b/apidocs/python/src/plugin.py index b393622a..517eb7a6 100644 --- a/apidocs/python/src/plugin.py +++ b/apidocs/python/src/plugin.py @@ -8,9 +8,9 @@ occurs. You need to define them in your module and they will automatically be us for callback events. To utilize full functionality, such as the ``prof.cons_show`` function, see ``prof`` -documentation and use: - :: - import prof +documentation and use:: + + import prof """ # Initialization and Lifecycle @@ -28,8 +28,8 @@ def prof_init(version: str, status: str, account_name: str | None, fulljid: str :param fulljid: The full Jabber ID (barejid/resource) of the logged-in user, or None if not logged in. :return: None - Example: - :: + 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}") """ @@ -42,8 +42,8 @@ def prof_on_start() -> None: :return: None - Example: - :: + Example:: + def prof_on_start() -> None: prof.cons_show("CProof has started...") """ @@ -56,8 +56,8 @@ def prof_on_shutdown() -> None: :return: None - Example: - :: + Example:: + def prof_on_shutdown() -> None: prof.cons_show("CProof is shutting down...") """ @@ -70,8 +70,8 @@ def prof_on_unload() -> None: :return: None - Example: - :: + Example:: + def prof_on_unload() -> None: prof.cons_show("Plugin unloaded") """ @@ -84,8 +84,8 @@ def prof_on_connect(account_name: str, fulljid: str) -> None: :param fulljid: The full Jabber ID (barejid/resource) of the connected account. :return: None - Example: - :: + Example:: + def prof_on_connect(account_name: str, fulljid: str) -> None: prof.cons_show(f"Connected as {account_name} ({fulljid})") """ @@ -98,8 +98,8 @@ def prof_on_disconnect(account_name: str, fulljid: str) -> None: :param fulljid: The full Jabber ID (barejid/resource) of the disconnected account. :return: None - Example: - :: + Example:: + def prof_on_disconnect(account_name: str, fulljid: str) -> None: prof.cons_show(f"Disconnected {account_name} ({fulljid})") """ @@ -118,8 +118,8 @@ def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> :param message: The received message. :return: The modified message to display, or None to preserve the original. - Example: - :: + Example:: + def prof_pre_chat_message_display(barejid: str, resource: str, message: str) -> str | None: new_message = f"{message} (from {barejid})" return new_message @@ -136,8 +136,8 @@ def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> :param message: The displayed message. :return: None - Example: - :: + Example:: + def prof_post_chat_message_display(barejid: str, resource: str, message: str) -> None: prof.cons_show(f"Displayed message from {barejid}/{resource}: {message}") """ @@ -152,8 +152,8 @@ def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: :param message: The message to be sent. :return: The modified message to send, or None to cancel sending. - Example: - :: + Example:: + def prof_pre_chat_message_send(barejid: str, message: str) -> str | None: return f"{message} (sent by plugin)" """ @@ -168,8 +168,8 @@ def prof_post_chat_message_send(barejid: str, message: str) -> None: :param message: The sent message. :return: None - Example: - :: + Example:: + def prof_post_chat_message_send(barejid: str, message: str) -> None: prof.cons_show(f"Sent to {barejid}: {message}") """ @@ -188,8 +188,8 @@ def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str :param message: The received message. :return: The modified message to display, or None to preserve the original. - Example: - :: + Example:: + def prof_pre_room_message_display(barejid: str, nick: str, message: str) -> str | None: return f"{message} (from {nick})" """ @@ -205,8 +205,8 @@ def prof_post_room_message_display(barejid: str, nick: str, message: str) -> Non :param message: The displayed message. :return: None - Example: - :: + Example:: + def prof_post_room_message_display(barejid: str, nick: str, message: str) -> None: prof.cons_show(f"Displayed in {barejid} from {nick}: {message}") """ @@ -221,8 +221,8 @@ def prof_pre_room_message_send(barejid: str, message: str) -> str | None: :param message: The message to be sent. :return: The modified message to send, or None to cancel sending. - Example: - :: + Example:: + def prof_pre_room_message_send(barejid: str, message: str) -> str | None: return f"{message} (sent by plugin)" """ @@ -237,8 +237,8 @@ def prof_post_room_message_send(barejid: str, message: str) -> None: :param message: The sent message. :return: None - Example: - :: + Example:: + def prof_post_room_message_send(barejid: str, message: str) -> None: prof.cons_show(f"Sent to {barejid}: {message}") """ @@ -253,8 +253,8 @@ def prof_on_room_history_message(barejid: str, nick: str, message: str, timestam :param timestamp: The message's original send time in ISO 8601 format (e.g., ``2025-09-10T19:45:00Z``). :return: None - Example: - :: + Example:: + 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}") """ @@ -273,8 +273,8 @@ def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str :param message: The received message. :return: The modified message to display, or None to preserve the original. - Example: - :: + Example:: + def prof_pre_priv_message_display(barejid: str, nick: str, message: str) -> str | None: return f"{message} (private from {nick})" """ @@ -290,8 +290,8 @@ def prof_post_priv_message_display(barejid: str, nick: str, message: str) -> Non :param message: The displayed message. :return: None - Example: - :: + 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}") """ @@ -307,8 +307,8 @@ def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | N :param message: The message to be sent. :return: The modified message to send, or None to cancel sending. - Example: - :: + Example:: + def prof_pre_priv_message_send(barejid: str, nick: str, message: str) -> str | None: return f"{message} (private to {nick})" """ @@ -324,8 +324,8 @@ def prof_post_priv_message_send(barejid: str, nick: str, message: str) -> None: :param message: The sent message. :return: None - Example: - :: + 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}") """ @@ -342,8 +342,8 @@ def prof_on_message_stanza_send(stanza: str) -> str | None: :param stanza: The XMPP message stanza to send. :return: The modified stanza to send, or None to preserve the original. - Example: - :: + Example:: + def prof_on_message_stanza_send(stanza: str) -> str | None: prof.cons_show(f"Sending message stanza: {stanza}") return stanza @@ -358,8 +358,8 @@ def prof_on_message_stanza_receive(stanza: str) -> bool: :param stanza: The received XMPP message stanza. :return: True to allow CProof to process the stanza, False to block processing. - Example: - :: + Example:: + def prof_on_message_stanza_receive(stanza: str) -> bool: prof.cons_show(f"Received message stanza: {stanza}") return True @@ -374,8 +374,8 @@ def prof_on_presence_stanza_send(stanza: str) -> str | None: :param stanza: The XMPP presence stanza to send. :return: The modified stanza to send, or None to preserve the original. - Example: - :: + Example:: + def prof_on_presence_stanza_send(stanza: str) -> str | None: prof.cons_show(f"Sending presence stanza: {stanza}") return stanza @@ -390,8 +390,8 @@ def prof_on_presence_stanza_receive(stanza: str) -> bool: :param stanza: The received XMPP presence stanza. :return: True to allow CProof to process the stanza, False to block processing. - Example: - :: + Example:: + def prof_on_presence_stanza_receive(stanza: str) -> bool: prof.cons_show(f"Received presence stanza: {stanza}") return True @@ -406,8 +406,8 @@ def prof_on_iq_stanza_send(stanza: str) -> str | None: :param stanza: The XMPP IQ stanza to send. :return: The modified stanza to send, or None to preserve the original. - Example: - :: + Example:: + def prof_on_iq_stanza_send(stanza: str) -> str | None: prof.cons_show(f"Sending IQ stanza: {stanza}") return stanza @@ -422,8 +422,8 @@ def prof_on_iq_stanza_receive(stanza: str) -> bool: :param stanza: The received XMPP IQ stanza. :return: True to allow CProof to process the stanza, False to block processing. - Example: - :: + Example:: + def prof_on_iq_stanza_receive(stanza: str) -> bool: prof.cons_show(f"Received IQ stanza: {stanza}") return True @@ -441,8 +441,8 @@ def prof_on_contact_offline(barejid: str, resource: str, status: str | None) -> :param status: The status message received with the offline presence, or None. :return: None - Example: - :: + 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'}") """ @@ -458,8 +458,8 @@ def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: :param priority: The priority associated with the resource. :return: None - Example: - :: + Example:: + def prof_on_contact_presence(barejid: str, resource: str, presence: str, status: str | None, priority: int) -> None: prof.notify(f"{barejid} is {presence}", 5000, "Presence") """ @@ -474,8 +474,8 @@ def prof_on_chat_win_focus(barejid: str) -> None: :param barejid: The Jabber ID of the chat window recipient (e.g., ``bob@example.com``). :return: None - Example: - :: + Example:: + def prof_on_chat_win_focus(barejid: str) -> None: prof.cons_show(f"Focused chat window for {barejid}") """ @@ -487,8 +487,8 @@ def prof_on_room_win_focus(barejid: str) -> None: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :return: None - Example: - :: + Example:: + def prof_on_room_win_focus(barejid: str) -> None: prof.cons_show(f"Focused room window for {barejid}") """ diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index d42168ee..f60d6f90 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -1,8 +1,8 @@ """ The prof module provides a Python API for plugins to interact with CProof. -Plugins must import this module to access its functions: -:: +Plugins must import this module to access its functions:: + import prof Functions are grouped into sections for console interaction, command management, @@ -20,10 +20,11 @@ class CommandCallback(Protocol): :param command_parameters: Variable string arguments passed to the callback. :return: None - Example: - :: + Example:: + def my_command(*command_parameters: str) -> None: prof.cons_show(f"Received: {command_parameters}") + """ def __call__(self, *command_parameters: str) -> None: ... @@ -32,10 +33,11 @@ class TimedCallback(Protocol): :return: None - Example: - :: + Example:: + def my_timed_callback() -> None: prof.cons_show("Timer triggered") + """ def __call__(self) -> None: ... @@ -46,10 +48,11 @@ class WindowCallback(Protocol): :param message: The message to process. :return: None - Example: - :: + Example:: + def my_window_callback(win_id: str, message: str) -> None: prof.win_show(win_id, f"Processed: {message}") + """ def __call__(self, win_id: str, message: str) -> None: ... @@ -61,9 +64,10 @@ def cons_alert() -> None: :return: None - Example: - :: + Example:: + prof.cons_alert() # Highlights the console window + """ pass @@ -73,9 +77,10 @@ def cons_show(message: str) -> None: :param message: The message to display. :return: None - Example: - :: + Example:: + prof.cons_show("This appears in the console window") + """ pass @@ -91,9 +96,10 @@ def cons_show_themed(group: str | None, key: str | None, default: str | None, me :param message: The message to display. :return: None - Example: - :: + Example:: + prof.cons_show_themed("myplugin", "text", "white", "Themed message") + """ pass @@ -103,9 +109,10 @@ def cons_bad_cmd_usage(command: str) -> None: :param command: The command name, including the leading slash (e.g., ``/say``). :return: None - Example: - :: + Example:: + prof.cons_bad_cmd_usage("/mycommand") # Shows usage error for /mycommand + """ pass @@ -138,8 +145,8 @@ def register_command( :param callback: Function to call when the command is executed, taking variable string arguments. :return: None - Example: - :: + Example:: + def command_handler(*args: str) -> None: prof.cons_show(f"Received: {args}") if len(args) == 1 and args[0] in ("on", "off"): @@ -159,6 +166,7 @@ def register_command( prof.register_command( "/new_command", 1, 2, synopsis, description, arguments, examples, command_handler ) + """ pass @@ -172,12 +180,13 @@ def register_timed(callback: TimedCallback, interval: int) -> None: :param interval: The time between calls, in seconds. :return: None - Example: - :: + Example:: + def periodic_task() -> None: prof.cons_show("Periodic update") prof.register_timed(periodic_task, 30) # Calls every 30 seconds + """ pass @@ -194,10 +203,11 @@ def completer_add(key: str, items: list[str]) -> None: :param items: The items to return on autocompletion. :return: None - Example: - :: + Example:: + prof.completer_add("/mycommand", ["action1", "action2"]) prof.completer_add("/mycommand dosomething", ["thing1", "thing2"]) + """ pass @@ -208,9 +218,10 @@ def completer_remove(key: str, items: list[str]) -> None: :param items: The items to remove from the autocomplete list. :return: None - Example: - :: + Example:: + prof.completer_remove("/mycommand", ["action1", "action2"]) + """ pass @@ -220,9 +231,10 @@ def completer_clear(key: str) -> None: :param key: The prefix to clear autocomplete items for (e.g., ``/mycommand``). :return: None - Example: - :: + Example:: + prof.completer_clear("/mycommand") + """ pass @@ -232,9 +244,10 @@ def filepath_completer_add(prefix: str) -> None: :param prefix: The prefix to trigger filepath autocompletion (e.g., ``/filecmd``). :return: None - Example: - :: + Example:: + prof.filepath_completer_add("/filecmd") # Enables filepath completion + """ pass @@ -247,10 +260,11 @@ def win_exists(tag: str) -> bool: :param tag: The tag identifying the plugin window. :return: True if the window exists, False otherwise. - Example: - :: + Example:: + if prof.win_exists("MyPlugin"): prof.cons_show("Window exists") + """ pass @@ -264,12 +278,13 @@ def win_create(tag: str, callback: WindowCallback) -> None: :param callback: Function to process window input, taking the window tag and message. :return: None - Example: - :: + Example:: + def handler(win_id: str, message: str) -> None: prof.win_show(win_id, f"Processed: {message}") prof.win_create("MyPlugin", handler) + """ pass @@ -279,9 +294,10 @@ def win_focus(tag: str) -> None: :param tag: The tag identifying the plugin window. :return: None - Example: - :: + Example:: + prof.win_focus("MyPlugin") # Focuses the MyPlugin window + """ pass @@ -292,9 +308,10 @@ def win_show(tag: str, message: str) -> None: :param message: The message to display. :return: None - Example: - :: + Example:: + prof.win_show("MyPlugin", "Message in plugin window") + """ pass @@ -311,9 +328,10 @@ def win_show_themed(tag: str, group: str | None, key: str | None, default: str | :param message: The message to display. :return: None - Example: - :: + Example:: + prof.win_show_themed("MyPlugin", "myplugin", "text", "white", "Themed message") + """ pass @@ -327,10 +345,11 @@ def chat_show(barejid: str, message: str) -> bool: :param message: The message to display. :return: True if the message was displayed, False if the chat window does not exist. - Example: - :: + Example:: + if prof.chat_show("bob@example.com", "Hello from plugin"): prof.cons_show("Message displayed") + """ pass @@ -355,9 +374,10 @@ def chat_show_themed( :param message: The message to display. :return: True if the message was displayed, False if the chat window does not exist. - Example: - :: + Example:: + prof.chat_show_themed("bob@example.com", "myplugin", "text", None, "!", "Themed message") + """ pass @@ -368,9 +388,10 @@ def room_show(roomjid: str, message: str) -> bool: :param message: The message to display. :return: True if the message was displayed, False if the room window does not exist. - Example: - :: + Example:: + prof.room_show("chat@conference.example.com", "Room message from plugin") + """ pass @@ -395,9 +416,10 @@ def room_show_themed( :param message: The message to display. :return: True if the message was displayed, False if the room window does not exist. - Example: - :: + Example:: + prof.room_show_themed("chat@conference.example.com", "myplugin", "text", None, "!", "Themed room message") + """ pass @@ -410,9 +432,10 @@ def send_line(line: str) -> None: :param line: The input line to execute (e.g., ``/who online``). :return: None - Example: - :: - prof.send_line("/who online") # Executes the /who online command + Example:: + + prof.send_line("/who online") # Executes the /who online command + """ pass @@ -422,11 +445,12 @@ def send_stanza(stanza: str) -> bool: :param stanza: The XMPP stanza to send (e.g., an IQ or message stanza). :return: True if the stanza was sent successfully, False if it was invalid or failed to send. - Example: - :: + Example:: + stanza = "" if prof.send_stanza(stanza): prof.cons_show("Stanza sent successfully") + """ pass @@ -438,9 +462,10 @@ def incoming_message(barejid: str, resource: str, message: str) -> None: :param message: The message text. :return: None - Example: - :: + Example:: + prof.incoming_message("bob@example.com", "laptop", "Hello from plugin") + """ pass @@ -453,9 +478,10 @@ def disco_add_feature(feature: str) -> None: :param feature: The service discovery feature to advertise (e.g., ``urn:xmpp:omemo:0``). :return: None - Example: - :: + Example:: + prof.disco_add_feature("urn:xmpp:omemo:0:devicelist+notify") + """ pass @@ -465,9 +491,10 @@ def encryption_reset(barejid: str) -> None: :param barejid: The Jabber ID of the contact (e.g., ``alice@example.com``). :return: None - Example: - :: + Example:: + prof.encryption_reset("alice@example.com") # Resets encryption + """ pass @@ -478,9 +505,10 @@ def chat_set_titlebar_enctext(barejid: str, enctext: str) -> bool: :param enctext: The text to display in the titlebar. :return: True if the text was set, False if the chat window does not exist. - Example: - :: + Example:: + prof.chat_set_titlebar_enctext("bob@example.com", "secure") + """ pass @@ -492,9 +520,10 @@ def chat_unset_titlebar_enctext(barejid: str) -> bool: :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :return: True if the text was reset, False if the chat window does not exist. - Example: - :: + Example:: + prof.chat_unset_titlebar_enctext("bob@example.com") + """ pass @@ -505,9 +534,10 @@ def chat_set_incoming_char(barejid: str, ch: str) -> bool: :param ch: The prefix character to display. :return: True if the character was set, False if the chat window does not exist. - Example: - :: - prof.chat_set_incoming_char("bob@example.com", "*") + Example:: + + prof.chat_set_incoming_char("bob@example.com", "*") + """ pass @@ -517,9 +547,10 @@ def chat_unset_incoming_char(barejid: str) -> bool: :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :return: True if the character was reset, False if the chat window does not exist. - Example: - :: + Example:: + prof.chat_unset_incoming_char("bob@example.com") + """ pass @@ -530,9 +561,10 @@ def chat_set_outgoing_char(barejid: str, ch: str) -> bool: :param ch: The prefix character to display. :return: True if the character was set, False if the chat window does not exist. - Example: - :: + Example:: + prof.chat_set_outgoing_char("bob@example.com", "+") + """ pass @@ -542,9 +574,10 @@ def chat_unset_outgoing_char(barejid: str) -> bool: :param barejid: The Jabber ID of the contact (e.g., ``bob@example.com``). :return: True if the character was reset, False if the chat window does not exist. - Example: - :: + Example:: + prof.chat_unset_outgoing_char("bob@example.com") + """ pass @@ -555,9 +588,10 @@ def room_set_titlebar_enctext(roomjid: str, enctext: str) -> bool: :param enctext: The text to display in the titlebar. :return: True if the text was set, False if the room window does not exist. - Example: - :: + Example:: + prof.room_set_titlebar_enctext("chat@conference.example.com", "secure") + """ pass @@ -569,9 +603,10 @@ def room_unset_titlebar_enctext(roomjid: str) -> bool: :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :return: True if the text was reset, False if the room window does not exist. - Example: - :: + Example:: + prof.room_unset_titlebar_enctext("chat@conference.example.com") + """ pass @@ -582,9 +617,10 @@ def room_set_message_char(roomjid: str, ch: str) -> bool: :param ch: The prefix character to display. :return: True if the character was set, False if the room window does not exist. - Example: - :: + Example:: + prof.room_set_message_char("chat@conference.example.com", "^") + """ pass @@ -594,9 +630,10 @@ def room_unset_message_char(roomjid: str) -> bool: :param roomjid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :return: True if the character was reset, False if the room window does not exist. - Example: - :: + Example:: + prof.room_unset_message_char("chat@conference.example.com") + """ pass @@ -613,9 +650,10 @@ def settings_boolean_get(group: str, key: str, default: bool) -> bool: :param default: The default value if the setting is not found. :return: The setting value, or the default if not found. - Example: - :: + Example:: + notify = prof.settings_boolean_get("myplugin", "notify", False) + """ pass @@ -629,9 +667,10 @@ def settings_boolean_set(group: str, key: str, value: bool) -> None: :param value: The boolean value to set. :return: None - Example: - :: - prof.settings_boolean_set("myplugin", "notify", True) + Example:: + + prof.settings_boolean_set("myplugin", "notify", True) + """ pass @@ -645,9 +684,10 @@ def settings_string_get(group: str, key: str, default: str) -> str: :param default: The default value if the setting is not found. :return: The setting value, or the default if not found. - Example: - :: + Example:: + prefix = prof.settings_string_get("myplugin", "prefix", "myplugin>") + """ pass @@ -661,9 +701,10 @@ def settings_string_set(group: str, key: str, value: str) -> None: :param value: The string value to set. :return: None - Example: - :: + Example:: + prof.settings_string_set("myplugin", "prefix", "myplugin>") + """ pass @@ -677,9 +718,10 @@ def settings_string_list_get(group: str, key: str) -> list[str]: :param key: The item name within the group. :return: List of strings, or an empty list if the setting does not exist. - Example: - :: + Example:: + items = prof.settings_string_list_get("myplugin", "items") + """ pass @@ -694,9 +736,10 @@ def settings_string_list_add(group: str, key: str, value: str) -> None: :param value: The string to add to the list. :return: None - Example: - :: + Example:: + prof.settings_string_list_add("myplugin", "items", "item1") + """ pass @@ -710,9 +753,10 @@ def settings_string_list_remove(group: str, key: str, value: str) -> bool: :param value: The string to remove from the list. :return: True if the item was removed or not in the list, False if the list does not exist. - Example: - :: + Example:: + prof.settings_string_list_remove("myplugin", "items", "item1") + """ pass @@ -725,9 +769,10 @@ def settings_string_list_clear(group: str, key: str) -> bool: :param key: The item name within the group. :return: True if the list was cleared, False if the list does not exist. - Example: - :: + Example:: + prof.settings_string_list_clear("myplugin", "items") + """ pass @@ -741,9 +786,10 @@ def settings_int_get(group: str, key: str, default: int) -> int: :param default: The default value if the setting is not found. :return: The setting value, or the default if not found. - Example: - :: + Example:: + timeout = prof.settings_int_get("myplugin", "timeout", 10) + """ pass @@ -757,9 +803,10 @@ def settings_int_set(group: str, key: str, value: int) -> None: :param value: The integer value to set. :return: None - Example: - :: + Example:: + prof.settings_int_set("myplugin", "timeout", 100) + """ pass @@ -771,11 +818,12 @@ def get_current_recipient() -> str | None: :return: The Jabber ID of the recipient (e.g., ``bob@example.com``), or None if not in a chat window. - Example: - :: + Example:: + recipient = prof.get_current_recipient() if recipient: prof.cons_show(f"Chatting with: {recipient}") + """ pass @@ -784,11 +832,12 @@ def get_current_muc() -> str | None: :return: The Jabber ID of the room (e.g., ``chat@conference.example.com``), or None if not in a chat room window. - Example: - :: + Example:: + room = prof.get_current_muc() if room: prof.cons_show(f"In room: {room}") + """ pass @@ -797,11 +846,12 @@ def get_current_nick() -> str | None: :return: The user's nickname (e.g., ``alice``), or None if not in a chat room window. - Example: - :: + Example:: + nick = prof.get_current_nick() if nick: prof.cons_show(f"Nickname: {nick}") + """ pass @@ -811,10 +861,11 @@ def get_name_from_roster(barejid: str) -> str: :param barejid: The Jabber ID to look up (e.g., ``bob@example.com``). :return: The nickname from the roster, or the input barejid if not found. - Example: - :: + Example:: + name = prof.get_name_from_roster("bob@example.com") prof.cons_show(f"Name: {name}") + """ pass @@ -824,11 +875,12 @@ def get_barejid_from_roster(name: str) -> str | None: :param name: The nickname to look up. :return: The Jabber ID (e.g., ``bob@example.com``), or None if the nickname is not in the roster. - Example: - :: + Example:: + jid = prof.get_barejid_from_roster("bob") if jid: prof.cons_show(f"JID: {jid}") + """ pass @@ -837,10 +889,11 @@ def get_current_occupants() -> list[str]: :return: List of occupant nicknames, or an empty list if not in a chat room window. - Example: - :: + Example:: + occupants = prof.get_current_occupants() prof.cons_show(f"Occupants: {', '.join(occupants)}") + """ pass @@ -850,10 +903,11 @@ def get_room_nick(barejid: str) -> str: :param barejid: The Jabber ID of the room (e.g., ``chat@conference.example.com``). :return: The user's nickname in the room. - Example: - :: + Example:: + nick = prof.get_room_nick("chat@conference.example.com") prof.cons_show(f"Room nick: {nick}") + """ pass @@ -862,10 +916,11 @@ def current_win_is_console() -> bool: :return: True if the console window is focused, False otherwise. - Example: - :: + Example:: + if prof.current_win_is_console(): prof.cons_show("Console is focused") + """ pass @@ -880,9 +935,10 @@ def notify(message: str, timeout: int, category: str) -> None: :param category: The notification category, displayed with the message. :return: None - Example: - :: + Example:: + prof.notify("New message received", 5000, "MyPlugin") + """ pass @@ -892,9 +948,10 @@ def log_debug(message: str) -> None: :param message: The message to log. :return: None - Example: - :: + Example:: + prof.log_debug("Debugging plugin initialization") + """ pass @@ -904,9 +961,10 @@ def log_info(message: str) -> None: :param message: The message to log. :return: None - Example: - :: + Example:: + prof.log_info("Plugin started successfully") + """ pass @@ -916,9 +974,10 @@ def log_warning(message: str) -> None: :param message: The message to log. :return: None - Example: - :: + Example:: + prof.log_warning("Configuration issue detected") + """ pass @@ -928,8 +987,9 @@ def log_error(message: str) -> None: :param message: The message to log. :return: None - Example: - :: + Example:: + prof.log_error("Failed to connect to server") + """ pass \ No newline at end of file -- 2.49.1 From 8849d9b79ef2cecc30575e91cae857ca80c27d64 Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Mon, 22 Sep 2025 23:05:45 +0200 Subject: [PATCH 4/5] docs: move callbacks down To improve readability of the docs --- apidocs/python/src/prof.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/apidocs/python/src/prof.py b/apidocs/python/src/prof.py index f60d6f90..2cdf4410 100644 --- a/apidocs/python/src/prof.py +++ b/apidocs/python/src/prof.py @@ -25,6 +25,7 @@ class CommandCallback(Protocol): def my_command(*command_parameters: str) -> None: prof.cons_show(f"Received: {command_parameters}") + .. :noindex: """ def __call__(self, *command_parameters: str) -> None: ... @@ -38,6 +39,7 @@ class TimedCallback(Protocol): def my_timed_callback() -> None: prof.cons_show("Timer triggered") + .. :noindex: """ def __call__(self) -> None: ... @@ -53,6 +55,7 @@ class WindowCallback(Protocol): def my_window_callback(win_id: str, message: str) -> None: prof.win_show(win_id, f"Processed: {message}") + .. :noindex: """ def __call__(self, win_id: str, message: str) -> None: ... -- 2.49.1 From 40dd773c6a41028c9cc6d1d3e3ea1127fc2f697f Mon Sep 17 00:00:00 2001 From: Jabber Developer Date: Tue, 23 Sep 2025 14:04:56 +0200 Subject: [PATCH 5/5] docs(apidocs/c): improve profapi.h and profhooks.h comments - Enhanced file-level comments with concise descriptions - Added usage examples and aligned with Python prof module style - Updated function comments to remove tables, improve clarity - Replaced Profanity with CProof, preserved paths and method names --- apidocs/c/profapi.h | 831 +++++++++++++++++++++++++++--------------- apidocs/c/profhooks.h | 295 ++++++++------- 2 files changed, 702 insertions(+), 424 deletions(-) diff --git a/apidocs/c/profapi.h b/apidocs/c/profapi.h index c6de34a8..96b67775 100644 --- a/apidocs/c/profapi.h +++ b/apidocs/c/profapi.h @@ -1,470 +1,721 @@ -/** @file -C plugin API. -*/ +/** @file profapi.h + * @brief C Plugin API for CProof. + * + * This header defines functions for CProof plugins to interact with the console, + * windows, commands, autocompletion, notifications, and settings. All functions are + * optional and can be called by plugins to handle events like message display or + * command execution. Plugins should implement hooks in profhooks.h for event-driven + * behavior. + * + * Include this header in your plugin and call functions as needed. Example: + * @code + * #include "profapi.h" + * prof_cons_show("Hello from plugin!"); + * @endcode + * + * @see profhooks.h + */ -/** \mainpage C Plugins API and Hooks -List of all API function available to plugins: {@link profapi.h} - -List of all hooks which plugins may implement: {@link profhooks.h} -*/ - -/** Type representing a window, used for referencing windows created by the plugin */ +/** Window handle for referencing plugin-created windows. */ typedef char* PROF_WIN_TAG; -/** Type representing a function pointer to a command callback */ +/** Function pointer for command callbacks, accepting an array of arguments. */ typedef void(*CMD_CB)(char **args); -/** Type representing a function pointer to a timed callback */ +/** Function pointer for timed callbacks, accepting no arguments. */ typedef void(*TIMED_CB)(void); -/** Type representing a function pointer to a window callback */ +/** Function pointer for window callbacks, accepting a window tag and input line. */ typedef void(*WINDOW_CB)(PROF_WIN_TAG win, char *line); -/** Highlights the console window in the status bar. */ +/** Highlights the console window in the status bar. */ void prof_cons_alert(void); /** -Show a message in the console window. -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in the console window. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_cons_show("This will appear in the console window"); + * @endcode + */ int prof_cons_show(const char * const message); /** -Show a message in the console, using the specified theme. -Themes are specified in ~/.local/share/profanity/plugin_themes -@param group the group name in the themes file -@param item the item name within the group -@param def default colour if the theme cannot be found -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in the console with a specified theme. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param group The group name in the themes file. + * @param item The item name within the group. + * @param def Default color if theme is not found. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_cons_show_themed("myplugin", "text", NULL, "Plugin themed message"); + * @endcode + */ int prof_cons_show_themed(const char *const group, const char *const item, const char *const def, const char *const message); /** -Show a message indicating the command has been called incorrectly. -@param cmd the command name with leading slash, e.g. "/say" -@return 1 on success, 0 on failure -*/ + * Shows a message indicating a command was used incorrectly. + * @param cmd The command name with leading slash (e.g., "/say"). + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_cons_bad_cmd_usage("/mycommand"); + * @endcode + */ int prof_cons_bad_cmd_usage(const char *const cmd); /** -Register a new command, with help information, and callback for command execution. -Profanity will do some basic validation when the command is called using the argument range. -@param command_name the command name with leading slash, e.g. "/say" -@param min_args minimum number or arguments that the command considers to be a valid call -@param max_args maximum number or arguments that the command considers to be a valid call -@param synopsis command usages -@param description a short description of the command -@param arguments argument descriptions -@param examples example usages -@param callback The {@link CMD_CB} function to execute when the command is invoked -*/ + * Registers a new command with help information and callback. + * CProof validates arguments using the specified range. + * @param command_name The command name with leading slash (e.g., "/say"). + * @param min_args Minimum number of valid arguments. + * @param max_args Maximum number of valid arguments. + * @param synopsis Command usage strings. + * @param description Short command description. + * @param arguments Argument descriptions as [arg, desc] pairs. + * @param examples Example usage strings. + * @param callback The @ref CMD_CB function to invoke. + * + * Example: + * @code + * char *synopsis[] = { "/newcommand action1|action2", "/newcommand print " }; + * char *args[][2] = { { "action1|action2", "Perform action" }, { "print ", "Print argument" } }; + * char *examples[] = { "/newcommand action1", "/newcommand print \"Test\"" }; + * prof_register_command("/newcommand", 1, 2, synopsis, "Example command", args, examples, my_function); + * @endcode + */ void prof_register_command(const char *command_name, int min_args, int max_args, char **synopsis, const char *description, char *arguments[][2], char **examples, CMD_CB callback); /** -Register a function that Profanity will call periodically. -@param callback The {@link TIMED_CB} function to execute -@param interval_seconds the time between each call to the function, in seconds -*/ + * Registers a function to be called periodically by CProof. + * @param callback The @ref TIMED_CB function to execute. + * @param interval_seconds Time between calls, in seconds. + * + * Example: + * @code + * prof_register_timed(my_function, 30); + * @endcode + */ void prof_register_timed(TIMED_CB callback, int interval_seconds); /** -Add values to be autocompleted by Profanity for a command, or command argument. If the key already exists, Profanity will add the items to the existing autocomplete items for that key. -@param key the prefix to trigger autocompletion -@param items the items to return on autocompletion -*/ + * Adds autocomplete values for a command or argument. + * @param key The prefix to trigger autocompletion. + * @param items Items to autocomplete. + * + * Example: + * @code + * char *items[] = { "action1", "action2", NULL }; + * prof_completer_add("/mycommand", items); + * @endcode + */ void prof_completer_add(const char *key, char **items); /** -Remove values from autocompletion for a command, or command argument. - -@param key the prefix from which to remove the autocompletion items -@param items the items to remove -*/ + * Removes autocomplete values for a command or argument. + * @param key The prefix to remove items from. + * @param items Items to remove. + * + * Example: + * @code + * char *items[] = { "action1", NULL }; + * prof_completer_remove("/mycommand", items); + * @endcode + */ void prof_completer_remove(const char *key, char **items); /** -Remove all values from autocompletion for a command, or command argument. - -@param key the prefix from which to clear the autocompletion items -*/ + * Clears all autocomplete values for a command or argument. + * @param key The prefix to clear. + * + * Example: + * @code + * prof_completer_clear("/mycommand"); + * @endcode + */ void prof_completer_clear(const char *key); /** -Add filepath autocompletion for a command, or command argument. - -@param prefix the prefix from which filepath autocompletion will be triggered -*/ + * Adds filepath autocompletion for a command or argument. + * @param prefix The prefix to trigger filepath autocompletion. + * + * Example: + * @code + * prof_filepath_completer_add("/filecmd"); + * @endcode + */ void prof_filepath_completer_add(const char *prefix); /** -Send a desktop notification. -@param message the message to display in the notification -@param timeout_ms the length of time before the notification disappears in milliseconds -@param category the category of the notification, also displayed -*/ + * Sends a desktop notification. + * @param message The message to display. + * @param timeout_ms Duration before the notification disappears (milliseconds). + * @param category The notification category. + * + * Example: + * @code + * prof_notify("Example notification", 5000, "Example plugin"); + * @endcode + */ void prof_notify(const char *message, int timeout_ms, const char *category); /** -Send a line of input to Profanity to execute. -@param line the line to send -*/ + * Sends a line of input to CProof to execute. + * @param line The command line to send. + * + * Example: + * @code + * prof_send_line("/who online"); + * @endcode + */ void prof_send_line(char *line); /** -Retrieve the Jabber ID of the current chat recipient, when in a chat window. -@return the Jabber ID of the current chat recipient e.g. "buddy@chat.org", or NULL if not in a chat window. -*/ + * Gets the Jabber ID of the current chat recipient. + * @return The Jabber ID (e.g., "buddy@example.com") or NULL if not in a chat window. + */ char* prof_get_current_recipient(void); /** -Retrieve the Jabber ID of the current room, when in a chat room window. -@return the Jabber ID of the current chat room e.g. "metalchat@conference.chat.org", or NULL if not in a chat room window. -*/ + * Gets the Jabber ID of the current chat room. + * @return The room Jabber ID (e.g., "metalchat@conference.example.com") or NULL if not in a room. + */ char* prof_get_current_muc(void); /** -Determine whether or not the Console window is currently focused. -@return 1 if the user is currently in the Console window, 0 otherwise. -*/ + * Checks if the console window is currently focused. + * @return 1 if in the console window, 0 otherwise. + */ int prof_current_win_is_console(void); /** -Retrieve the users nickname in a chat room, when in a chat room window. -@return the users nickname in the current chat room e.g. "eddie", or NULL if not in a chat room window. -*/ + * Gets the user’s nickname in the current chat room. + * @return The nickname (e.g., "eddie") or NULL if not in a room. + */ char* prof_get_current_nick(void); /** -Retrieve the nickname for a given barejid if it is in the roster. -@return the users nickname e.g. "eddie", or the input barejid if it is not in the roster. -*/ + * Gets the nickname for a barejid from the roster. + * @param barejid The Jabber ID. + * @return The nickname (e.g., "eddie") or the barejid if not in the roster. + */ char* prof_get_name_from_roster(const char *barejid); /** -Retrieve the barejid for a given nickname if it is in the roster. -@return the users barejid e.g. "eddie@server.tld", or NULL if the nickname is not in the roster. -*/ + * Gets the barejid for a nickname from the roster. + * @param name The nickname. + * @return The barejid (e.g., "eddie@server.tld") or NULL if not in the roster. + */ char* prof_get_barejid_from_roster(const char *name); /** -Retrieve nicknames of all occupants in a chat room, when in a chat room window. -@return nicknames of all occupants in the current room or an empty list if not in a chat room window. -*/ + * Gets nicknames of all occupants in the current chat room. + * @return List of nicknames or an empty list if not in a room. + */ char** prof_get_current_occupants(void); /** -Retrieve current nickname used in chat room. -@param barejid The room's Jabber ID -@return Room nickname. -*/ + * Gets the current nickname in a chat room. + * @param barejid The room’s Jabber ID. + * @return The nickname. + */ char* prof_get_room_nick(const char *barejid); /** -Write to the Profanity log at level DEBUG. -@param message The message to log -*/ + * Logs a debug message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_debug("Debug message"); + * @endcode + */ void prof_log_debug(const char *message); /** -Write to the Profanity log at level INFO. -@param message The message to log -*/ + * Logs an info message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_info("Info message"); + * @endcode + */ void prof_log_info(const char *message); /** -Write to the Profanity log at level WARNING. -@param message The message to log -*/ + * Logs a warning message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_warning("Warning message"); + * @endcode + */ void prof_log_warning(const char *message); /** -Write to the Profanity log at level ERROR. -@param message The message to log -*/ + * Logs an error message to the CProof log. + * @param message The message to log. + * + * Example: + * @code + * prof_log_error("Error message"); + * @endcode + */ void prof_log_error(const char *message); /** -Create a plugin window. -@param win The {@link PROF_WIN_TAG} used to refer to the window -@param input_handler The WINDOW_CB function to call when the window receives input -*/ + * Creates a plugin window. + * @param win The @ref PROF_WIN_TAG to refer to the window. + * @param input_handler The @ref WINDOW_CB function for input handling. + * + * Example: + * @code + * prof_win_create("My Plugin", window_handler); + * @endcode + */ void prof_win_create(PROF_WIN_TAG win, WINDOW_CB input_handler); /** -Determine whether or not a plugin window currently exists for {@link PROF_WIN_TAG}. -@param win the {@link PROF_WIN_TAG} used when creating the plugin window -@return 1 if the window exists, 0 otherwise -*/ + * Checks if a plugin window exists. + * @param win The @ref PROF_WIN_TAG of the window. + * @return 1 if the window exists, 0 otherwise. + * + * Example: + * @code + * prof_win_exists("My Plugin"); + * @endcode + */ int prof_win_exists(PROF_WIN_TAG win); /** -Focus plugin window. -@param win the {@link PROF_WIN_TAG} of the window to focus -@return 1 on success, 0 on failure -*/ + * Focuses a plugin window. + * @param win The @ref PROF_WIN_TAG of the window. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_win_focus("My Plugin"); + * @endcode + */ int prof_win_focus(PROF_WIN_TAG win); /** -Show a message in the plugin window. -@param win the {@link PROF_WIN_TAG} of the window to display the message -@param message The message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a plugin window. + * @param win The @ref PROF_WIN_TAG of the window. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_win_show("My Plugin", "Message in plugin window"); + * @endcode + */ int prof_win_show(PROF_WIN_TAG win, char *message); /** -Show a message in the plugin window, using the specified theme. -Themes are specified in ~/.local/share/profanity/plugin_themes -@param tag The {@link PROF_WIN_TAG} of the window to display the message -@param group the group name in the themes file -@param key the item name within the group -@param def default colour if the theme cannot be found or NULL -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a plugin window with a specified theme. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param tag The @ref PROF_WIN_TAG of the window. + * @param group The group name in the themes file. + * @param key The item name within the group. + * @param def Default color if theme is not found or NULL. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_win_show_themed("My Plugin", "myplugin", "text", NULL, "Themed message"); + * @endcode + */ int prof_win_show_themed(PROF_WIN_TAG tag, char *group, char *key, char *def, char *message); /** -Send an XMPP stanza -@param stanza an XMPP stanza -@return 1 if the stanza was sent successfully, 0 otherwise -*/ + * Sends an XMPP stanza. + * @param stanza The XMPP stanza to send. + * @return 1 if sent successfully, 0 otherwise. + * + * Example: + * @code + * prof_send_stanza(""); + * @endcode + */ int prof_send_stanza(char *stanza); /** -Get a boolean setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param def default value if setting not found -@return the setting, or default value -*/ + * Gets a boolean setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param def Default value if not found. + * @return The setting or default value. + * + * Example: + * @code + * prof_settings_boolean_get("myplugin", "notify", 0); + * @endcode + */ int prof_settings_boolean_get(char *group, char *key, int def); /** -Set a boolean setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value value to set -*/ + * Sets a boolean setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value The value to set. + * + * Example: + * @code + * prof_settings_boolean_set("myplugin", "activate", 1); + * @endcode + */ void prof_settings_boolean_set(char *group, char *key, int value); /** -Get a string setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param def default value if setting not found -@return the setting, or default value -*/ + * Gets a string setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param def Default value if not found. + * @return The setting or default value. + * + * Example: + * @code + * prof_settings_string_get("myplugin", "prefix", "prefix-->"); + * @endcode + */ char* prof_settings_string_get(char *group, char *key, char *def); /** -Set a string setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value value to set -*/ + * Sets a string setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value The value to set. + * + * Example: + * @code + * prof_settings_string_set("myplugin", "prefix", "myplugin, "); + * @endcode + */ void prof_settings_string_set(char *group, char *key, char *value); /** -Get a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -The string list setting items are separated by semicolons. -@param group the group name in the settings file -@param key the item name within the group -@return the list setting -*/ + * Gets a string list setting, separated by semicolons. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @return The list setting. + * + * Example: + * @code + * prof_settings_string_list_get("myplugin", "somelist"); + * @endcode + */ char** prof_settings_string_list_get(char *group, char *key); /** -Add an item to a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -If the list does not exist, a new one will be created with the element added -@param group the group name in the settings file -@param key the item name within the group -@param value item to add -*/ + * Adds an item to a string list setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * Creates a new list if none exists. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value The item to add. + * + * Example: + * @code + * prof_settings_string_list_add("myplugin", "somelist", "anelement"); + * @endcode + */ void prof_settings_string_list_add(char *group, char *key, char *value); /** -Remove an item from a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value item to remove -@return 1 if the item was removed, or is not in the list, 0 if the list does not exist -*/ + * Removes an item from a string list setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value The item to remove. + * @return 1 if removed or not in the list, 0 if the list does not exist. + * + * Example: + * @code + * prof_settings_string_list_remove("myplugin", "somelist", "anelement"); + * @endcode + */ int prof_settings_string_list_remove(char *group, char *key, char *value); /** -Remove all items from a string list setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@return 1 if the list was cleared, 0 if the list does not exist -*/ + * Clears all items from a string list setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @return 1 if cleared, 0 if the list does not exist. + * + * Example: + * @code + * prof_settings_string_list_clear("myplugin", "somelist"); + * @endcode + */ int prof_settings_string_list_clear(char *group, char *key); /** -Get an integer setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param def default value if setting not found -@return the setting, or default value -*/ + * Gets an integer setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param def Default value if not found. + * @return The setting or default value. + * + * Example: + * @code + * prof_settings_int_get("myplugin", "timeout", 10); + * @endcode + */ int prof_settings_int_get(char *group, char *key, int def); /** -Set an integer setting -Settings must be specified in ~/.local/share/profanity/plugin_settings -@param group the group name in the settings file -@param key the item name within the group -@param value value to set -*/ + * Sets an integer setting. + * Settings are in ~/.local/share/profanity/plugin_settings. + * @param group The group name in the settings file. + * @param key The item name within the group. + * @param value The value to set. + * + * Example: + * @code + * prof_settings_int_set("myplugin", "timeout", 100); + * @endcode + */ void prof_settings_int_set(char *group, char *key, int value); /** -Trigger incoming message handling, this plugin will make profanity act as if the message has been received -@param barejid Jabber ID of the sender of the message -@param resource resource of the sender of the message -@param message the message text -*/ + * Triggers handling of an incoming message as if received by CProof. + * @param barejid Jabber ID of the sender. + * @param resource Resource of the sender. + * @param message The message text. + * + * Example: + * @code + * prof_incoming_message("bob@server.org", "laptop", "Hello there"); + * @endcode + */ void prof_incoming_message(char *barejid, char *resource, char *message); /** -Add a service discovery feature the list supported by Profanity. -If a session is already connected, a presence update will be sent to allow any client/server caches to update their feature list for Profanity -@param feature the service discovery feature to be added -*/ + * Adds a service discovery feature to CProof’s supported features. + * Sends a presence update if a session is connected. + * @param feature The feature to add. + * + * Example: + * @code + * prof_disco_add_feature("urn:xmpp:omemo:0:devicelist+notify"); + * @endcode + */ void prof_disco_add_feature(char *feature); /** -End any encrypted session with the specified user. -@param barejid Jabber ID of the recipient -*/ + * Ends an encrypted session with a user. + * @param barejid Jabber ID of the recipient. + * + * Example: + * @code + * prof_encryption_reset("alice@server.org"); + * @endcode + */ void prof_encryption_reset(char *barejid); /** -Set the text to display in the titlebar encryption indicator for recipient. -@param barejid Jabber ID of the recipient -@param enctext The text to display -@return 1 on success, 0 on failure -*/ + * Sets the titlebar encryption indicator text for a recipient. + * @param barejid Jabber ID of the recipient. + * @param enctext The text to display. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_set_titlebar_enctext("bob@example.com", "safe"); + * @endcode + */ int prof_chat_set_titlebar_enctext(char *barejid, char *enctext); /** -Let profanity decide what to show in the titlebar encryption indicator for recipient. -@param barejid Jabber ID of the recipient -@return 1 on success, 0 on failure -*/ + * Resets the titlebar encryption indicator for a recipient to CProof’s default. + * @param barejid Jabber ID of the recipient. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_unset_titlebar_enctext("bob@example.com"); + * @endcode + */ int prof_chat_unset_titlebar_enctext(char *barejid); /** -Set the incoming message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@param ch The character to display -@return 1 on success, 0 on failure -*/ + * Sets the incoming message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @param ch The character to display. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_set_incoming_char("kristine@example.com", "*"); + * @endcode + */ int prof_chat_set_incoming_char(char *barejid, char *ch); /** -Reset the incoming message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@return 1 on success, 0 on failure -*/ + * Resets the incoming message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_unset_incoming_char("kristine@example.com"); + * @endcode + */ int prof_chat_unset_incoming_char(char *barejid); /** -Set the outgoing message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@param ch The character to display -@return 1 on success, 0 on failure -*/ + * Sets the outgoing message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @param ch The character to display. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_set_outgoing_char("david@example.com", "+"); + * @endcode + */ int prof_chat_set_outgoing_char(char *barejid, char *ch); /** -Reset the outgoing message prefix character for specified contact. -@param barejid Jabber ID of the recipient -@return 1 on success, 0 on failure -*/ + * Resets the outgoing message prefix character for a contact. + * @param barejid Jabber ID of the recipient. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_unset_outgoing_char("david@example.com"); + * @endcode + */ int prof_chat_unset_outgoing_char(char *barejid); /** -Set the text to display in the titlebar encryption indicator for room. -@param roomjid Jabber ID of the room -@param enctext The text to display -@return 1 on success, 0 on failure -*/ + * Sets the titlebar encryption indicator text for a room. + * @param roomjid Jabber ID of the room. + * @param enctext The text to display. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_room_set_titlebar_enctext("generalchat@conference.service.com", "secret"); + * @endcode + */ int prof_room_set_titlebar_enctext(char *roomjid, char *enctext); /** -Let profanity decide what to show in the titlebar encryption indicator for room. -@param roomjid Jabber ID of the room -@return 1 on success, 0 on failure -*/ + * Resets the titlebar encryption indicator for a room to CProof’s default. + * @param roomjid Jabber ID of the room. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_room_unset_titlebar_enctext("generalchat@conference.service.com"); + * @endcode + */ int prof_room_unset_titlebar_enctext(char *roomjid); /** -Set the message prefix character for specified room. -@param roomjid Jabber ID of the room -@param ch The character to display -@return 1 on success, 0 on failure -*/ + * Sets the message prefix character for a room. + * @param roomjid Jabber ID of the room. + * @param ch The character to display. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_room_set_message_char("ohnoes@conference.example.com", "^"); + * @endcode + */ int prof_room_set_message_char(char *roomjid, char *ch); /** -Reset the message prefix character for specified room. -@param roomjid Jabber ID of the room -@return 1 on success, 0 on failure -*/ + * Resets the message prefix character for a room. + * @param roomjid Jabber ID of the room. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_room_unset_message_char("ohnoes@conference.example.com"); + * @endcode + */ int prof_room_unset_message_char(char *roomjid); /** -Show a message in a chat window. -@param barejid Jabber ID of the recipient -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat window. + * @param barejid Jabber ID of the recipient. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_show("bob@server.org", "From a plugin in the chat window"); + * @endcode + */ int prof_chat_show(char *barejid, char *message); /** -Show a message in a chat window, using the specified theme, and prefix character -Themes are specified in ~/.local/share/profanity/plugin_themes -@param barejid Jabber ID of the recipient -@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 -@param ch The character to prefix the message, or NULL for default behaviour -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat window with a theme and prefix character. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @param barejid Jabber ID of the recipient. + * @param group The group name in the themes file or NULL. + * @param item The item name within the group or NULL. + * @param def Default color if theme is not found. + * @param ch The prefix character or NULL for default. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_chat_show_themed("bob@server.org", "myplugin", "text", NULL, "!", "Themed message"); + * @endcode + */ int prof_chat_show_themed(char *barejid, char *group, char *item, char *def, char *ch, char *message); /** -Show a message in a chat room window. -@param roomjid Jabber ID of the room -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat room window. + * @param roomjid Jabber ID of the room. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_room_show("chat@conference.example.com", "From a plugin in the chat room"); + * @endcode + */ 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 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 -@param ch The character to prefix the message, or NULL for default behaviour -@param message the message to print -@return 1 on success, 0 on failure -*/ + * Shows a message in a chat room window with a theme and prefix character. + * Themes are in ~/.local/share/profanity/plugin_themes. + * @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 color if theme is not found. + * @param ch The prefix character or NULL for default. + * @param message The message to print. + * @return 1 on success, 0 on failure. + * + * Example: + * @code + * prof_room_show_themed("chat@conference.example.com", "myplugin", "text", NULL, "!", "Themed message"); + * @endcode + */ int prof_room_show_themed(char *roomjid, char *group, char *item, char *def, char *ch, char *message); diff --git a/apidocs/c/profhooks.h b/apidocs/c/profhooks.h index c789454d..29725ad7 100644 --- a/apidocs/c/profhooks.h +++ b/apidocs/c/profhooks.h @@ -1,220 +1,247 @@ -/** @file -C Hooks. -*/ +/** @file profhooks.h + * @brief C Plugin Hooks for CProof. + * + * This header defines optional callback hooks that CProof plugins can implement to + * handle events such as startup, shutdown, message processing, and presence updates in + * CProof, a console-based XMPP client. These hooks are called by CProof when the + * corresponding events occur, allowing plugins to customize behavior. All hooks are + * optional; plugins can define only the hooks they need, and CProof will automatically + * invoke them when appropriate. + * + * To use these hooks, define the functions in your plugin with the signatures provided + * in this header. For example, to handle the startup event: + * + * @code + * #include "profhooks.h" + * void prof_on_start(void) { + * // Handle CProof startup + * } + * @endcode + * + * For additional plugin functionality, such as displaying messages or registering + * commands, see the CProof API functions in profapi.h. + * + * @see profapi.h + */ + +/** @mainpage CProof Plugins API and Hooks + * List of all API functions available to plugins: @ref profapi.h + * List of all hooks which plugins may implement: @ref profhooks.h + */ /** -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 -@param status the package status of Profanity, "development" or "release" -@param account_name account name of the currently logged in account, or NULL if not logged in -@param fulljid the users full Jabber ID (barejid and resource) if logged in, NULL otherwise -*/ + * Called when a plugin is loaded, either when CProof is started, or when the /plugins load or /plugins install commands are called + * @param version The version of CProof + * @param status The package status of CProof, "development" or "release" + * @param account_name Account name of the currently logged in account, or NULL if not logged in + * @param fulljid The user's full Jabber ID (barejid and resource) if logged in, NULL otherwise + */ void prof_init(const char * const version, const char * const status, const char *const account_name, const char *const fulljid); /** -Called when Profanity is started -*/ + * Called when CProof is started + */ void prof_on_start(void); /** -Called when the user quits Profanity -*/ + * Called when the user quits CProof + */ void prof_on_shutdown(void); /** -Called when a plugin is unloaded with the /plugins unload command -*/ + * Called when a plugin is unloaded with the /plugins unload command + */ void prof_on_unload(void); /** -Called when the user connects with an account -@param account_name account name of the account used for logging in -@param fulljid the full Jabber ID (barejid and resource) of the account -*/ + * Called when the user connects with an account + * @param account_name Account name of the account used for logging in + * @param fulljid The full Jabber ID (barejid and resource) of the account + */ void prof_on_connect(const char * const account_name, const char * const fulljid); /** -Called when the user disconnects an account -@param account_name account name of the account being disconnected -@param fulljid the full Jabber ID (barejid and resource) of the account -*/ + * Called when the user disconnects an account + * @param account_name Account name of the account being disconnected + * @param fulljid The full Jabber ID (barejid and resource) of the account + */ void prof_on_disconnect(const char * const account_name, const char * const fulljid); /** -Called before a chat message is displayed -@param barejid Jabber ID of the message sender -@param resource resource of the message sender -@param message the received message -@return the new message to display, or NULL to preserve the original message -*/ + * Called before a chat message is displayed + * @param barejid Jabber ID of the message sender + * @param resource Resource of the message sender + * @param message The received message + * @return The new message to display, or NULL to preserve the original message + */ char* prof_pre_chat_message_display(const char * const barejid, const char *const resource, const char *message); /** -Called after a chat message is displayed -@param barejid Jabber ID of the message sender -@param resource resource of the message sender -@param message the received message -*/ + * Called after a chat message is displayed + * @param barejid Jabber ID of the message sender + * @param resource Resource of the message sender + * @param message The received message + */ void prof_post_chat_message_display(const char * const barejid, const char *const resource, const char *message); /** -Called before a chat message is sent -@param barejid Jabber ID of the message recipient -@param message the message to be sent -@return the modified or original message to send, or NULL to cancel sending of the message -*/ + * Called before a chat message is sent + * @param barejid Jabber ID of the message recipient + * @param message The message to be sent + * @return The modified or original message to send, or NULL to cancel sending of the message + */ char* prof_pre_chat_message_send(const char * const barejid, const char *message); /** -Called after a chat message has been sent -@param barejid Jabber ID of the message recipient -@param message the sent message -*/ + * Called after a chat message has been sent + * @param barejid Jabber ID of the message recipient + * @param message The sent message + */ void prof_post_chat_message_send(const char * const barejid, const char *message); /** -Called before a chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of message sender -@param message the received message -@return the new message to display, or NULL to preserve the original message -*/ + * Called before a chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of message sender + * @param message The received message + * @return The new message to display, or NULL to preserve the original message + */ char* prof_pre_room_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called after a chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of the message sender -@param message the received message -*/ + * Called after a chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of the message sender + * @param message The received message + */ void prof_post_room_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called before a chat room message is sent -@param barejid Jabber ID of the room -@param message the message to be sent -@return the modified or original message to send, or NULL to cancel sending of the message -*/ + * Called before a chat room message is sent + * @param barejid Jabber ID of the room + * @param message The message to be sent + * @return The modified or original message to send, or NULL to cancel sending of the message + */ char* prof_pre_room_message_send(const char * const barejid, const char *message); /** -Called after a chat room message has been sent -@param barejid Jabber ID of the room -@param message the sent message -*/ + * Called after a chat room message has been sent + * @param barejid Jabber ID of the room + * @param message The sent message + */ void prof_post_room_message_send(const char * const barejid, const char *message); /** -Called when the server sends a chat room history message -@param barejid Jabber ID of the room -@param nick nickname of the message sender -@param message the message to be sent -@param timestamp time the message was originally sent to the room, in ISO8601 format -*/ + * Called when the server sends a chat room history message + * @param barejid Jabber ID of the room + * @param nick Nickname of the message sender + * @param message The message to be sent + * @param timestamp Time the message was originally sent to the room, in ISO8601 format + */ void prof_on_room_history_message(const char * const barejid, const char *const nick, const char *const message, const char *const timestamp); /** -Called before a private chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of message sender -@param message the received message -@return the new message to display, or NULL to preserve the original message -*/ + * Called before a private chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of message sender + * @param message The received message + * @return The new message to display, or NULL to preserve the original message + */ char* prof_pre_priv_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called after a private chat room message is displayed -@param barejid Jabber ID of the room -@param nick nickname of the message sender -@param message the received message -*/ + * Called after a private chat room message is displayed + * @param barejid Jabber ID of the room + * @param nick Nickname of the message sender + * @param message The received message + */ void prof_post_priv_message_display(const char * const barejid, const char * const nick, const char *message); /** -Called before a private chat room message is sent -@param barejid Jabber ID of the room -@param nick nickname of message recipient -@param message the message to be sent -@return the modified or original message to send, or NULL to cancel sending of the message -*/ + * Called before a private chat room message is sent + * @param barejid Jabber ID of the room + * @param nick Nickname of message recipient + * @param message The message to be sent + * @return The modified or original message to send, or NULL to cancel sending of the message + */ char* prof_pre_priv_message_send(const char * const barejid, const char * const nick, const char *message); /** -Called after a private chat room message has been sent -@param barejid Jabber ID of the room -@param nick nickname of the message recipient -@param message the sent message -*/ + * Called after a private chat room message has been sent + * @param barejid Jabber ID of the room + * @param nick Nickname of the message recipient + * @param message The sent message + */ void prof_post_priv_message_send(const char * const barejid, const char * const nick, const char *message); /** -Called before an XMPP message stanza is sent -@param stanza The stanza to send -@return The new stanza to send, or NULL to preserve the original stanza -*/ + * Called before an XMPP message stanza is sent + * @param stanza The stanza to send + * @return The new stanza to send, or NULL to preserve the original stanza + */ char* prof_on_message_stanza_send(const char *const stanza); /** -Called when an XMPP message stanza is received -@param stanza The stanza received -@return 1 if Profanity should continue to process the message stanza, 0 otherwise -*/ + * Called when an XMPP message stanza is received + * @param stanza The stanza received + * @return 1 if CProof should continue to process the message stanza, 0 otherwise + */ int prof_on_message_stanza_receive(const char *const stanza); /** -Called before an XMPP presence stanza is sent -@param stanza The stanza to send -@return The new stanza to send, or NULL to preserve the original stanza -*/ + * Called before an XMPP presence stanza is sent + * @param stanza The stanza to send + * @return The new stanza to send, or NULL to preserve the original stanza + */ char* prof_on_presence_stanza_send(const char *const stanza); /** -Called when an XMPP presence stanza is received -@param stanza The stanza received -@return 1 if Profanity should continue to process the presence stanza, 0 otherwise -*/ + * Called when an XMPP presence stanza is received + * @param stanza The stanza received + * @return 1 if CProof should continue to process the presence stanza, 0 otherwise + */ int prof_on_presence_stanza_receive(const char *const stanza); /** -Called before an XMPP iq stanza is sent -@param stanza The stanza to send -@return The new stanza to send, or NULL to preserve the original stanza -*/ + * Called before an XMPP iq stanza is sent + * @param stanza The stanza to send + * @return The new stanza to send, or NULL to preserve the original stanza + */ char* prof_on_iq_stanza_send(const char *const stanza); /** -Called when an XMPP iq stanza is received -@param stanza The stanza received -@return 1 if Profanity should continue to process the iq stanza, 0 otherwise -*/ + * Called when an XMPP iq stanza is received + * @param stanza The stanza received + * @return 1 if CProof should continue to process the iq stanza, 0 otherwise + */ int prof_on_iq_stanza_receive(const char *const stanza); /** -Called when a contact goes offline -@param barejid Jabber ID of the contact -@param resource the resource being disconnected -@param status the status message received with the offline presence, or NULL -*/ + * Called when a contact goes offline + * @param barejid Jabber ID of the contact + * @param resource The resource being disconnected + * @param status The status message received with the offline presence, or NULL + */ void prof_on_contact_offline(const char *const barejid, const char *const resource, const char *const status); /** -Called when a presence notification is received from a contact -@param barejid Jabber ID of the contact -@param resource the resource being disconnected -@param presence presence of the contact, one of "chat", "online", "away", "xa" or "dnd" -@param status the status message received with the presence, or NULL -@param priority the priority associated with the resource -*/ + * Called when a presence notification is received from a contact + * @param barejid Jabber ID of the contact + * @param resource The resource being disconnected + * @param presence Presence of the contact, one of "chat", "online", "away", "xa" or "dnd" + * @param status The status message received with the presence, or NULL + * @param priority The priority associated with the resource + */ void prof_on_contact_presence(const char *const barejid, const char *const resource, const char *const presence, const char *const status, const int priority); /** -Called when a chat window is focused -@param barejid Jabber ID of the chat window recipient -*/ + * Called when a chat window is focused + * @param barejid Jabber ID of the chat window recipient + */ void prof_on_chat_win_focus(const char *const barejid); /** -Called when a chat room window is focused -@param barejid Jabber ID of the room -*/ -void prof_on_room_win_focus(const char *const barejid); + * Called when a chat room window is focused + * @param barejid Jabber ID of the room + */ +void prof_on_room_win_focus(const char *const barejid); \ No newline at end of file -- 2.49.1