From e189c0efd02405c6db5091f22c81d06ead6a262d Mon Sep 17 00:00:00 2001 From: baldurk Date: Fri, 13 Dec 2024 15:07:01 +0000 Subject: [PATCH] Manually link to callback types in docstrings * The auto-type in parameters does not get linked, but we can manually link it in the docstring text. --- qrenderdoc/Code/Interface/Extensions.h | 10 ++++++++++ qrenderdoc/Code/Interface/QRDInterface.h | 13 ++++++++++++- renderdoc/api/replay/renderdoc_replay.h | 11 +++++++++++ 3 files changed, 33 insertions(+), 1 deletion(-) diff --git a/qrenderdoc/Code/Interface/Extensions.h b/qrenderdoc/Code/Interface/Extensions.h index 4f321aef1..910e28edb 100644 --- a/qrenderdoc/Code/Interface/Extensions.h +++ b/qrenderdoc/Code/Interface/Extensions.h @@ -385,6 +385,7 @@ immediately before returning. context as needed. :param InvokeCallback callback: The callback to invoke on the UI thread. + Callback function signature must match :func:`InvokeCallback`. )"); virtual void InvokeOntoUIThread(InvokeCallback callback) = 0; @@ -403,6 +404,7 @@ added in a vertical layout. :param WidgetCallback closed: A callback that will be called when the widget is closed by the user. This implicitly deletes the widget and all its children, which will no longer be valid even if a handle to them exists. + Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. :rtype: QWidget )"); @@ -715,6 +717,7 @@ The widget needs to be added to a parent to become part of a panel or window. DOCUMENT(R"(Create a normal button widget. :param WidgetCallback pressed: Callback to be called when the button is pressed. + Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. :rtype: QWidget )"); @@ -811,6 +814,7 @@ checkerboard to be rendered instead. This is the default behaviour when a widget created the checkbox is unchecked. :param WidgetCallback changed: Callback to be called when the widget is toggled. + Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. :rtype: QWidget )"); @@ -823,6 +827,7 @@ Upon creation the radio box is unchecked, even in a group of other radio boxes t If you want a default radio box to be checked, you should use :meth:`SetWidgetChecked`. :param WidgetCallback changed: Callback to be called when the widget is toggled. + Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. :rtype: QWidget )"); @@ -893,6 +898,7 @@ happen. :param bool singleLine: ``True`` if the widget should be a single-line entry, otherwise it is a multi-line text box. :param WidgetCallback changed: Callback to be called when the text in the textbox is changed. + Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. :rtype: QWidget )"); @@ -907,6 +913,7 @@ When created there are no pre-defined entries in the drop-down section. This can well as being able to select a pre-defined entry. :param WidgetCallback changed: Callback to be called when the text in the combobox is changed. This will be called both when a new option is selected or when the user edits the text. + Callback function signature must match :func:`WidgetCallback`. :return: The handle to the newly created widget. :rtype: QWidget )"); @@ -1081,6 +1088,7 @@ struct IExtensionManager last string will be the name of the menu item itself. Must contain at least one entry, or two entries if ``base`` is :data:`WindowMenu.NewMenu`. :param ExtensionCallback callback: The function to callback when the menu item is selected. + Callback function signature must match :func:`ExtensionCallback`. )"); virtual void RegisterWindowMenu(WindowMenu base, const rdcarray &submenus, ExtensionCallback callback) = 0; @@ -1096,6 +1104,7 @@ struct IExtensionManager :param List[str] submenus: A list of strings containing the submenus to add before the item. The last string will be the name of the menu item itself. Must contain at least one entry. :param ExtensionCallback callback: The function to callback when the menu item is selected. + Callback function signature must match :func:`ExtensionCallback`. )"); virtual void RegisterPanelMenu(PanelMenu base, const rdcarray &submenus, ExtensionCallback callback) = 0; @@ -1111,6 +1120,7 @@ struct IExtensionManager :param List[str] submenus: A list of strings containing the submenus to add before the item. The last string will be the name of the menu item itself. Must contain at least one entry. :param ExtensionCallback callback: The function to callback when the menu item is selected. + Callback function signature must match :func:`ExtensionCallback`. )"); virtual void RegisterContextMenu(ContextMenu base, const rdcarray &submenus, ExtensionCallback callback) = 0; diff --git a/qrenderdoc/Code/Interface/QRDInterface.h b/qrenderdoc/Code/Interface/QRDInterface.h index ac3de3766..843335987 100644 --- a/qrenderdoc/Code/Interface/QRDInterface.h +++ b/qrenderdoc/Code/Interface/QRDInterface.h @@ -170,6 +170,7 @@ will be invoked, if it exists. for a global shortcut. Note that if an existing global shortcut exists the new one will not be registered. :param ShortcutCallback callback: The function to callback when the shortcut is hit. + Callback function signature must match :func:`ShortcutCallback`. )"); virtual void RegisterShortcut(const rdcstr &shortcut, QWidget *widget, ShortcutCallback callback) = 0; @@ -207,7 +208,7 @@ DOCUMENT(R"(The event browser window. Not a member function - the signature for any ``EventFilterCallback`` callbacks. Called for each event in a capture when performing filtering in the Event Browser. The associated - ``FilterParseCallback`` will be called first to parse the parameters, and is available for caching + :func:`FilterParseCallback` will be called first to parse the parameters, and is available for caching or syntax checking. The same filter name and params string will be passed to this function. :param CaptureContext context: The current capture context. @@ -343,10 +344,13 @@ expression. what each filter means. :param EventFilterCallback filter: The callback to call for each candidate event to perform filtering. + Callback function signature must match :func:`EventFilterCallback`. :param FilterParseCallback parser: The callback to call when the parsing the parameters and checking for any errors. This can be ``None`` if no pre-parsing is required. + Callback function signature must match :func:`FilterParseCallback`. :param AutoCompleteCallback completer: The callback to call when trying to provide autocomplete suggestions. This can be ``None`` if no completion is desired/applicable. + Callback function signature must match :func:`AutoCompleteCallback`. :return: Whether or not the registration was successful. :rtype: bool )"); @@ -1468,6 +1472,7 @@ blocking fashion on the current thread. :param bool synchronous: If a capture is open, then ``True`` will use :meth:`BlockInvoke` to call the callback. Otherwise if ``False`` then :meth:`AsyncInvoke` will be used. :param DirectoryBrowseCallback callback: The function to callback on the replay thread. + Callback function signature must match :func:`DirectoryBrowseCallback`. )"); virtual void GetHomeFolder(bool synchronous, DirectoryBrowseCallback callback) = 0; @@ -1480,6 +1485,7 @@ blocking fashion on the current thread. :param bool synchronous: If a capture is open, then ``True`` will use :meth:`BlockInvoke` to call the callback. Otherwise if ``False`` then :meth:`AsyncInvoke` will be used. :param DirectoryBrowseCallback callback: The function to callback on the replay thread. + Callback function signature must match :func:`DirectoryBrowseCallback`. )"); virtual void ListFolder(const rdcstr &path, bool synchronous, DirectoryBrowseCallback callback) = 0; @@ -1524,12 +1530,14 @@ comes in, we remove any other requests in the queue before it that have the same :param str tag: The tag to identify this callback. :param InvokeCallback method: The function to callback on the replay thread. + Callback function signature must match :func:`InvokeCallback`. )"); virtual void AsyncInvoke(const rdcstr &tag, InvokeCallback method) = 0; DOCUMENT(R"(Make a non-blocking invoke call onto the replay thread. :param InvokeCallback method: The function to callback on the replay thread. + Callback function signature must match :func:`InvokeCallback`. )"); virtual void AsyncInvoke(InvokeCallback method) = 0; @@ -1539,6 +1547,7 @@ comes in, we remove any other requests in the queue before it that have the same DOCUMENT(R"(Make a blocking invoke call onto the replay thread. :param InvokeCallback method: The function to callback on the replay thread. + Callback function signature must match :func:`InvokeCallback`. )"); virtual void BlockInvoke(InvokeCallback method) = 0; @@ -2564,8 +2573,10 @@ place if needed. :param renderdoc.ShaderCompileFlags flags: The flags originally used to compile the shader. :param ShaderViewer.SaveCallback saveCallback: The callback function to call when a save/update is triggered. + Callback function signature must match :func:`ShaderViewer.SaveCallback`. :param ShaderViewer.RevertCallback revertCallback: The callback function to call when the shader is to be reverted - either by user request or because the shader viewer was closed. + Callback function signature must match :func:`ShaderViewer.RevertCallback`. :return: The new :class:`ShaderViewer` window opened but not shown for editing. :rtype: ShaderViewer )"); diff --git a/renderdoc/api/replay/renderdoc_replay.h b/renderdoc/api/replay/renderdoc_replay.h index dcfe556d2..a25434c2d 100644 --- a/renderdoc/api/replay/renderdoc_replay.h +++ b/renderdoc/api/replay/renderdoc_replay.h @@ -1222,6 +1222,7 @@ The details of the types of messages that can be received are listed under :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value when a long blocking message is coming through, e.g. a capture copy. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: The message that was received. :rtype: TargetControlMessage )"); @@ -1322,6 +1323,7 @@ separate thread. fail. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the resolver process. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: The result of the operation. :rtype: ResultDetails )"); @@ -1453,6 +1455,7 @@ the capture must be available on the machine where the replay happens. :param str filename: The path to the file on the local system. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the copy. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: The path on the remote system where the capture was saved temporarily. :rtype: str )"); @@ -1466,6 +1469,7 @@ This function will block until the copy is fully complete, or an error has occur :param str localpath: The local path where the file should be saved. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the copy. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. )"); virtual void CopyCaptureFromRemote(const rdcstr &remotepath, const rdcstr &localpath, RENDERDOC_ProgressCallback progress) = 0; @@ -1488,6 +1492,7 @@ or an error has occurred. :param ReplayOptions opts: The options controlling how the capture should be replayed. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the opening. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: A tuple containing the status of opening the capture, whether success or failure, and the resulting :class:`ReplayController` handle if successful. :rtype: Tuple[ResultDetails,ReplayController] @@ -1530,6 +1535,7 @@ empty or unrecognised. :param str filetype: The format of the given file. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: The result of the operation. :rtype: ResultDetails )"); @@ -1546,6 +1552,7 @@ For the :paramref:`OpenBuffer.filetype` parameter, see :meth:`OpenFile`. :param str filetype: The format of the given file. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value if an import step occurs. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: The result of the operation. :rtype: ResultDetails )"); @@ -1579,6 +1586,7 @@ representation back to native RDC. again. If ``None`` then structured data will be fetched if not already present and used. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the conversion. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: The result of the operation. :rtype: ResultDetails )"); @@ -1666,6 +1674,7 @@ by the :class:`ReplayController`. :param ReplayOptions opts: The options controlling how the capture should be replayed. :param ProgressCallback progress: A callback that will be repeatedly called with an updated progress value for the opening. Can be ``None`` if no progress is desired. + Callback function signature must match :func:`ProgressCallback`. :return: A tuple containing the status of opening the capture, whether success or failure, and the resulting :class:`ReplayController` handle if successful. :rtype: Tuple[ResultDetails,ReplayController] @@ -1945,8 +1954,10 @@ This function will block until a remote connection tells the server to shut down :param int port: The port to listen on, or ``0`` to listen on the default port. :param KillCallback killReplay: A callback that returns a ``bool`` indicating if the server should be shut down or not. + Callback function signature must match :func:`KillCallback`. :param PreviewWindowCallback previewWindow: A callback that returns information for a preview window when the server wants to display some preview of the ongoing replay. + Callback function signature must match :func:`PreviewWindowCallback`. )"); extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_BecomeRemoteServer( const rdcstr &listenhost, uint16_t port, RENDERDOC_KillCallback killReplay,