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.
2026-05-04 09:00:44 +00:00 · 2024-12-13 15:07:01 +00:00
parent fb4a6645fc
commit e189c0efd0
3 changed files with 33 additions and 1 deletions
@@ -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<rdcstr> &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<rdcstr> &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<rdcstr> &submenus,
                                   ExtensionCallback callback) = 0;
@@ -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
 )");
@@ -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,