Clean up docstrings in python interfaces to be strictly typed/formatted

* Also added a script that can run as part of CI to verify that the docstring
  matches, by generating a regex from the docstring documented parameter types
  and return type and making sure we find a match within the C headers. This
  ensures all parameters are documented with the right types, no extra
  parameters are documented, and the return type is correct.
* The script also checks proper scoping so that if qrenderdoc docstrings
  mention a renderdoc type, they need to scope it properly.

.github/workflows/ci.yml

@@ -151,6 +151,7 @@ jobs:
       run: |
         cd docs
         make html SPHINXOPTS=-W
+        python3 ./docs/verify-docstrings.py
   linux:
     name: Linux
     needs: [commit-msg, clang-format]

docs/verify-docstrings.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+
+import sys
+import re
+import os
+import glob
+import argparse
+from enum import EnumMeta
+from typing import List
+
+import struct
+
+os.chdir(os.path.realpath(os.path.dirname(__file__)))
+
+# path to module libraries for windows
+if struct.calcsize("P") == 8:
+    binpath = '../x64/'
+else:
+    binpath = '../Win32/'
+
+# Prioritise release over development builds
+sys.path.insert(0, os.path.abspath(binpath + 'Development/pymodules'))
+sys.path.insert(0, os.path.abspath(binpath + 'Release/pymodules'))
+
+# Add the build paths to PATH so renderdoc.dll can be located
+os.environ["PATH"] = os.path.abspath(binpath + 'Development/') + os.pathsep + os.environ["PATH"]
+os.environ["PATH"] = os.path.abspath(binpath + 'Release/') + os.pathsep + os.environ["PATH"]
+
+# path to module libraries for linux
+sys.path.insert(0, os.path.abspath('../build/lib'))
+
+import renderdoc as rd
+import qrenderdoc as qrd
+
+parser = argparse.ArgumentParser()
+parser.add_argument('-p', '--path', help="Add a path to interface files to search (can be used multiple times)", action='append')
+parser.add_argument('-d', '--dump-combined', help="Set a path to dump the combined header that's being searched through", type=str)
+parser.add_argument('--debug-mismatches', help="Set a path to a folder, each mismatch creates a file in here with the failure", type=str)
+parser.add_argument('-v', '--verbose',
+                    help="Run verbosely", action="store_true")
+args = parser.parse_args()
+
+paths = ['../renderdoc/api/replay', '../qrenderdoc/Code/Interface']
+if args.path is not None:
+    paths += args.path
+
+if args.verbose:
+    print("Searching for interface files in: {}".format(paths))
+
+headers = ''
+
+for path in paths:
+    for f in glob.glob(os.path.join(os.path.abspath(path), '**', '*.h'), recursive=True):
+        if args.verbose:
+            print("Adding interface file {}".format(f))
+        with open(f, 'r') as file:
+            headers += file.read()
+            
+if args.dump_combined is not None:
+    with open(args.dump_combined, 'w') as file:
+        file.write(headers)
+
+if args.debug_mismatches is not None and os.path.isdir(args.debug_mismatches):
+    for f in glob.glob(os.path.join(os.path.abspath(args.debug_mismatches), '*')):
+        if args.verbose:
+            print("Removing {} in debug mismatches folder".format(f))
+        os.unlink(f)
+
+def make_c_type(ret: str, pattern: bool, typelist: List[str]):
+    orig_type = ret
+
+    # strip namespace
+    if ret[0:10] == 'renderdoc.':
+        ret = ret[10:]
+
+    # Handle pipelines that are renamed
+    if ret == 'D3D11State':
+        ret = 'D3D11Pipe::State'
+    elif ret == 'D3D12State':
+        ret = 'D3D12Pipe::State'
+    elif ret == 'GLState':
+        ret = 'GLPipe::State'
+    elif ret == 'VKState':
+        ret = 'VKPipe::State'
+
+    if ret in ['bool', 'void']:
+        pass
+    elif ret == 'str':
+        ret = '(const )?rdc(inflexible)?str ?[&*]?' if pattern else 'rdcstr'
+    elif ret == 'int':
+        ret = '(u?int[163264]{2}|size)_t' if pattern else 'int' # ambiguous
+    elif ret == 'float':
+        ret = 'float|double' if pattern else 'float'
+    elif ret == 'bytes':
+        ret = '(const )?bytebuf ?[&*]?' if pattern else 'bytebuf'
+    elif ret[0:5] == 'List[':
+        inner = make_c_type(ret[5:-1], pattern, typelist)
+        ret = '(const )?rdcarray<{}> ?[&*]?'.format(inner) if pattern else 'rdcarray<{}>'.format(inner)
+    elif ret[0:6] == 'Tuple[':
+        inners = [make_c_type(i.strip(), pattern, typelist) for i in ret[6:-1].split(',')]
+        if pattern:
+            inner = ',\s*'.join(inners)
+        else:
+            inner = ', '.join(inners)
+        ret = '(const )?rdcpair<{}> ?[&*]?'.format(inner) if pattern else 'rdcpair<{}>'.format(inner)
+    elif pattern:
+        if ret[-8:] == 'Callback':
+            ret = '(RENDERDOC_)?{}'.format(ret)
+        else:
+            if orig_type not in typelist:
+                typelist.append(orig_type)
+
+            ret = '(const )?I?{} ?[&*]?'.format(ret)
+        
+    return ret
+
+RTYPE_PATTERN = re.compile(r":rtype: (.*)")
+PARAM_PATTERN = re.compile(r":param ([^:]*) ([^: ]*):")
+
+count = 0
+
+def check_function(parent_name, objname, obj, source, global_func, typelist):
+    global count, args
+
+    if args.verbose:
+        print("Checking {} function {}.{}".format('global' if global_func else 'member', parent_name, objname))
+
+    docstring = obj.__doc__
+
+    params = PARAM_PATTERN.findall(docstring)
+
+    funcargs = ['', '']
+    for p in params:
+        if len(funcargs[0]) > 0:
+            funcargs[0] += ',\s*'
+            funcargs[1] += ', '
+        funcargs[0] += make_c_type(p[0], True, typelist) + ' ?' + p[1] + "(\s*=[^,]*)?"
+        funcargs[1] += make_c_type(p[0], False, typelist) + ' ' + p[1]
+
+    result = RTYPE_PATTERN.search(docstring)
+    if result is not None:
+        ret = result.group(1)
+    else:
+        ret = 'void'
+
+    global_pattern = ''
+    if global_func:
+        global_pattern = '(RENDERDOC_CC\s*RENDERDOC_)?'
+
+    pattern = '(?s){} ?{}{}\(\s*{}\)'.format(make_c_type(ret, True, typelist), global_pattern, objname, funcargs[0])
+    clean = '{} {}({})'.format(make_c_type(ret, False, typelist), objname, funcargs[1])
+
+    match = re.search(pattern, source, re.MULTILINE | re.DOTALL)
+
+    pattern2 = None
+    # global functions returning strings can't return an rdcstr, they have to return const char *
+    if match is None and ret == 'str':
+        pattern2 = '(?s)const char \*{}{}\(\s*{}\)'.format(global_pattern, objname, funcargs[0])
+        match = re.search(pattern2, source, re.MULTILINE | re.DOTALL)
+
+    if match is None:
+        count += 1
+        print("Error {:3} in {}: {}".format(count, parent_name, clean))
+        if args.debug_mismatches is not None and os.path.isdir(args.debug_mismatches):
+            with open(os.path.join(os.path.abspath(args.debug_mismatches), '{:03}-{}.{}.txt'.format(count, parent_name, objname)), 'w') as file:
+                file.write("# Failed to find matching declaration for {}.{}\n".format(parent_name, objname))
+                file.write("#\n")
+                file.write("# Matched against {}\n".format(pattern))
+                if pattern2 is not None:
+                    file.write("# Matched against {}\n".format(pattern2))
+                file.write("#\n")
+                file.write("#\n")
+                file.write("\n")
+                file.write("\n")
+                file.write(source)
+
+def check_used_types(objname, module, used_types):
+    global count
+
+    if args.verbose:
+        print('Checking {} referenced types: {}'.format(objname, module, used_types))
+
+    for t in used_types:
+        type_name = t
+        parent = module
+
+        while True:
+            if t in dir(parent):
+                break
+
+            # Allow some types that are opaque
+            if parent == rd and t in ['ANativeWindow', 'NSView', 'CALayer', 'wl_display', 'wl_surface', 'HWND', 'xcb_connection_t', 'xcb_window_t', 'Display', 'Drawable']:
+                break
+
+            if parent == qrd and t in ['QWidget']:
+                break
+
+            idx = t.find('.')
+            if idx >= 0:
+                parent_name = t[0:idx]
+                if parent_name in dir(parent):
+                    parent = parent.__dict__[parent_name]
+                elif parent_name == 'renderdoc':
+                    parent = rd
+                elif parent_name == 'qrenderdoc':
+                    parent = qrd
+                t = t[idx+1:]
+                continue
+
+            count += 1
+            print("Error {:3} in {}: Unrecognised reference {}".format(count, objname, type_name))
+            if type_name in dir(rd):
+                print("  - Maybe missing namespace to refer to renderdoc.{}?".format(type_name))
+            break
+
+for mod_name in ['renderdoc', 'qrenderdoc']:
+    mod = sys.modules[mod_name]
+    if args.verbose:
+        print("===== Checks for {} =====".format(mod_name))
+    for objname in dir(mod):
+        if re.search('__|SWIG|ResourceId_Null|rdcarray_of|Structured.*List', objname):
+            continue
+
+        # skip some functions that have special bindings and won't be easily found
+        if objname in ['CreateRemoteServerConnection', 'DumpObject', 'GetDefaultCaptureOptions', 'GetSupportedDeviceProtocols']:
+            if args.verbose:
+                print("Skipping {}".format(objname))
+            continue
+
+        obj = mod.__dict__[objname]
+
+        docstring = obj.__doc__
+
+        if 'INTERNAL:' in docstring:
+            continue
+
+        qualname = '{}.{}'.format(mod_name, objname)
+
+        if isinstance(obj, EnumMeta):
+            if args.verbose:
+                print("Skipping enum {}".format(qualname))
+
+            # don't check enums
+            continue
+        elif isinstance(obj, type):
+            if args.verbose:
+                print("Checking class {}".format(qualname))
+
+            # Grab the source to just this class to search in
+            source = re.search('(struct|class|union) I?' + objname + '(\n|\s*:[^A-Za-z][\s:a-zA-Z]*\n)\{.*?^}', headers, re.MULTILINE | re.DOTALL)
+            
+            namespace = None
+
+            if source is None and objname[0:2] in ['VK', 'GL']:
+                pipe = objname[0:2] + 'Pipe'
+                objname = objname[2:]
+
+                namespace = re.search('namespace ' + pipe + '.* namespace ' + pipe, headers, re.MULTILINE | re.DOTALL)
+                namespace = namespace.group(0)
+
+            if source is None and objname[0:5] in ['D3D11', 'D3D12']:
+                pipe = objname[0:5] + 'Pipe'
+                objname = objname[5:]
+
+                namespace = re.search('namespace ' + pipe + '.* namespace ' + pipe, headers, re.MULTILINE | re.DOTALL)
+                namespace = namespace.group(0)
+
+            if source is None and namespace is not None:
+                source = re.search('(struct|class|union) I?' + objname + '[^{]*\{.*?^}', headers, re.MULTILINE | re.DOTALL)
+                
+            source = source.group(0)
+
+            for member_name in obj.__dict__.keys():
+                if '__' in member_name or member_name in ['this', 'thisown']:
+                    continue
+
+                member = obj.__dict__[member_name]
+
+                # Skip some known functions that cannot be easily matched this way
+                if '{}.{}'.format(objname, member_name) in ['RemoteHost.Connect',
+                                                            'CaptureContext.EditShader',
+                                                            'ReplayController.DebugThread',
+                                                            'ReplayController.GetHistogram',
+                                                            'SDObject.AddChild',
+                                                            'SDObject.AsInt',
+                                                            'SDObject.AsFloat',
+                                                            'SDObject.AsString']:
+                    if args.verbose:
+                        print("Skipping {}.{}".format(objname, member_name))
+                    continue
+
+                if callable(member):
+                    used_types = []
+
+                    check_function(qualname, member_name, member, source, False, used_types)
+
+                    check_used_types('{}.{}'.format(qualname, member_name), mod, used_types)
+        elif callable(obj):
+            used_types = []
+
+            # check the function in all headers globally
+            check_function(mod_name, objname, obj, headers, True, used_types)
+
+            check_used_types(qualname, mod, used_types)
+
+print("{} mismatches detected".format(count))
+sys.exit(count)

qrenderdoc/Code/CaptureContext.cpp

@@ -2000,11 +2000,6 @@ void CaptureContext::SetResourceCustomName(ResourceId id, const rdcstr &name)
   RefreshUIStatus({}, true, true);
 }
 
-int CaptureContext::ResourceNameCacheID()
-{
-  return m_CustomNameCachedID;
-}
-
 #if defined(RENDERDOC_PLATFORM_APPLE)
 extern "C" void *makeNSViewMetalCompatible(void *handle);
 #endif
@@ -2459,7 +2454,7 @@ IConstantBufferPreviewer *CaptureContext::ViewConstantBuffer(ShaderStage stage,
   return new ConstantBufferPreviewer(*this, stage, slot, idx, m_MainWindow);
 }
 
-IPixelHistoryView *CaptureContext::ViewPixelHistory(ResourceId texID, int x, int y,
+IPixelHistoryView *CaptureContext::ViewPixelHistory(ResourceId texID, uint32_t x, uint32_t y,
                                                     const TextureDisplay &display)
 {
   return new PixelHistoryView(*this, texID, QPoint(x, y), display, m_MainWindow);

qrenderdoc/Code/CaptureContext.h

@@ -170,7 +170,7 @@ public:
   bool IsAutogeneratedName(ResourceId id) override;
   bool HasResourceCustomName(ResourceId id) override;
   void SetResourceCustomName(ResourceId id, const rdcstr &name) override;
-  int ResourceNameCacheID() override;
+  int32_t ResourceNameCacheID() override { return m_CustomNameCachedID; }
   TextureDescription *GetTexture(ResourceId id) override { return m_Textures[id]; }
   const rdcarray<TextureDescription> &GetTextures() override { return m_TextureList; }
   BufferDescription *GetBuffer(ResourceId id) override { return m_Buffers[id]; }
@@ -184,7 +184,7 @@ public:
   WindowingData CreateWindowingData(QWidget *window) override;
 
   const rdcarray<DebugMessage> &DebugMessages() override { return m_DebugMessages; }
-  int UnreadMessageCount() override { return m_UnreadMessageCount; }
+  int32_t UnreadMessageCount() override { return m_UnreadMessageCount; }
   void MarkMessagesRead() override { m_UnreadMessageCount = 0; }
   void AddMessages(const rdcarray<DebugMessage> &msgs) override;
 
@@ -264,7 +264,7 @@ public:
 
   IConstantBufferPreviewer *ViewConstantBuffer(ShaderStage stage, uint32_t slot,
                                                uint32_t idx) override;
-  IPixelHistoryView *ViewPixelHistory(ResourceId texID, int x, int y,
+  IPixelHistoryView *ViewPixelHistory(ResourceId texID, uint32_t x, uint32_t y,
                                       const TextureDisplay &display) override;
 
   QWidget *CreateBuiltinWindow(const rdcstr &objectName) override;

qrenderdoc/Code/Interface/Extensions.h

@@ -333,10 +333,18 @@ basic UI building tools for simple data input and display which can be used on a
   :param CaptureContext context: The current capture context.
   :param QWidget widget: The widget sending the callback.
   :param str text: Additional data for the call, such as the current or selected text.
+
+.. function:: InvokeCallback(context, widget, text)
+
+  Not a member function - the signature for any ``InvokeCallback`` callbacks.
+
+  Callback for invoking onto the UI thread from another thread (in particular the replay thread).
+  Takes no parameters as the callback is expected to store its own state.
 )");
 struct IMiniQtHelper
 {
   typedef std::function<void(ICaptureContext *, QWidget *, rdcstr)> WidgetCallback;
+  typedef std::function<void()> InvokeCallback;
 
   DOCUMENT(R"(Invoke a callback on the UI thread. All widget accesses must come from the UI thread,
 so if work has been done on the render thread then this function can be used to asynchronously and
@@ -349,9 +357,9 @@ immediately before returning.
   No parameters are provided to the callback, it is assumed that the callback will maintain its own
   context as needed.
 
-:param function callback: The callback to invoke on the UI thread.
+:param InvokeCallback callback: The callback to invoke on the UI thread.
 )");
-  virtual void InvokeOntoUIThread(std::function<void()> callback) = 0;
+  virtual void InvokeOntoUIThread(InvokeCallback callback) = 0;
 
   // top level widgets
 
@@ -369,7 +377,7 @@ added in a vertical layout.
   This implicitly deletes the widget and all its children, which will no longer be valid even if a
   handle to them exists.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateToplevelWidget(const rdcstr &windowTitle, WidgetCallback closed) = 0;
 
@@ -406,10 +414,10 @@ should only be used for debugging as the name may change even if for the same ty
 
   DOCUMENT(R"(Find a child widget of a parent by internal name.
 
-:param QWidget widget: The widget to start the search from.
+:param QWidget parent: The widget to start the search from.
 :param str name: The internal name to search for.
 :return: The handle to the first widget with a matching name, or ``None`` if no widget is found.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *FindChildByName(QWidget *parent, const rdcstr &name) = 0;
 
@@ -423,7 +431,7 @@ should only be used for debugging as the name may change even if for the same ty
 :param QWidget widget: The widget to query.
 :return: The handle to the parent widget with a matching name, or ``None`` if this widget is either
   not yet parented or is a top-level window.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *GetParent(QWidget *widget) = 0;
 
@@ -434,16 +442,16 @@ layout type widgets.
 :return: The number of child widgets this widget has.
 :rtype: int
 )");
-  virtual int GetNumChildren(QWidget *widget) = 0;
+  virtual int32_t GetNumChildren(QWidget *widget) = 0;
 
   DOCUMENT(R"(Return a child widget for a parent.
 
 :param QWidget parent: The parent widget to look up.
 :param int index: The child index to return.
 :return: The specified child of the parent, or ``None`` if the index is out of bounds.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
-  virtual QWidget *GetChild(QWidget *parent, int index) = 0;
+  virtual QWidget *GetChild(QWidget *parent, int32_t index) = 0;
 
   DOCUMENT(R"(Destroy a widget. Widgets stay alive unless explicitly destroyed here, OR in one other
 case when they are in a widget hiearchy under a top-level window which the user closes, which can
@@ -498,7 +506,7 @@ which typically has some widgets be only large enough for their content and othe
 'greedy' evenly divide any remaining free space.
 
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateHorizontalContainer() = 0;
 
@@ -511,7 +519,7 @@ which typically has some widgets be only large enough for their content and othe
 'greedy' evenly divide any remaining free space.
 
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateVerticalContainer() = 0;
 
@@ -524,7 +532,7 @@ which typically has some widgets be only large enough for their content and othe
 'greedy' evenly divide any remaining free space. This will not violate the grid constraint though.
 
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateGridContainer() = 0;
 
@@ -537,7 +545,7 @@ the same container will be minimally sized. This can be useful for simple layout
   spacer should consume vertical space. Typically this matches the direction of the layout it is
   in.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateSpacer(bool horizontal) = 0;
 
@@ -559,8 +567,8 @@ happen and the widget will not be added anywhere.
 :param int rowSpan: How many rows should this child span over.
 :param int columnSpan: How many columns should this child span over.
 )");
-  virtual void AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan,
-                             int columnSpan) = 0;
+  virtual void AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child,
+                             int32_t rowSpan, int32_t columnSpan) = 0;
 
   DOCUMENT(R"(Adds a child widget to the end of an ordered layout (either horizontal or vertical).
 If the parent is not an ordered layout nothing will happen and the widget will not be added anywhere.
@@ -580,7 +588,7 @@ added anywhere.
   of children will append the widget
 :param QWidget child: The child widget to add.
 )");
-  virtual void InsertWidget(QWidget *parent, int index, QWidget *child) = 0;
+  virtual void InsertWidget(QWidget *parent, int32_t index, QWidget *child) = 0;
 
   // widget manipulation
 
@@ -609,7 +617,7 @@ add text next to it.
 :param bool bold: ``True`` if the font should be bold.
 :param bool italic: ``True`` if the font should be italic.
 )");
-  virtual void SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold,
+  virtual void SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold,
                              bool italic) = 0;
 
   DOCUMENT(R"(Set whether the widget is enabled or not. This generally only affects interactive
@@ -636,7 +644,7 @@ data.
 in the hierarchy but is not visible and cannot be interacted with in any way.
 
 :param QWidget widget: The widget to show or hide.
-:param bool enabled: ``True`` if the widget should be made visible (shown).
+:param bool visible: ``True`` if the widget should be made visible (shown).
 )");
   virtual void SetWidgetVisible(QWidget *widget, bool visible) = 0;
 
@@ -664,7 +672,7 @@ The widget needs to be added to a parent to become part of a panel or window.
 :param bool collapsible: ``True`` if the groupbox should have a toggle in its header to allow
   collapsing its contents down vertically.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateGroupBox(bool collapsible) = 0;
 
@@ -672,7 +680,7 @@ The widget needs to be added to a parent to become part of a panel or window.
 
 :param WidgetCallback pressed: Callback to be called when the button is pressed.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateButton(WidgetCallback pressed) = 0;
 
@@ -682,7 +690,7 @@ The widget needs to be added to a parent to become part of a panel or window.
   This widget will be blank by default, you can set the text with :meth:`SetWidgetText`.
 
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateLabel() = 0;
 
@@ -693,7 +701,7 @@ creating the output as well as call :meth:`SetWidgetReplayOutput` to notify the
 current output.
 
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateOutputRenderingWidget() = 0;
 
@@ -711,9 +719,9 @@ cause the widget to go into an undefined state unless an output is created to re
 .. note::
   This function must be called on the main UI thread.
 
-:param QWidget window: The widget to create windowing data for.
+:param QWidget widget: The widget to create windowing data for.
 :return: The windowing data.
-:rtype: ~renderdoc.WindowingData
+:rtype: renderdoc.WindowingData
 )");
   virtual WindowingData GetWidgetWindowingData(QWidget *widget) = 0;
 
@@ -727,7 +735,7 @@ When a capture is closed and all outputs are destroyed, the widget will automati
 output so there is no need to do that manually.
 
 :param QWidget widget: The widget to set the output for.
-:param ~renderdoc.ReplayOutput output: The new output to set, or ``None`` to unset any previous
+:param renderdoc.ReplayOutput output: The new output to set, or ``None`` to unset any previous
   output.
 )");
   virtual void SetWidgetReplayOutput(QWidget *widget, IReplayOutput *output) = 0;
@@ -752,7 +760,7 @@ created the checkbox is unchecked.
 
 :param WidgetCallback changed: Callback to be called when the widget is toggled.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateCheckbox(WidgetCallback changed) = 0;
 
@@ -764,7 +772,7 @@ If you want a default radio box to be checked, you should use :meth:`SetWidgetCh
 
 :param WidgetCallback changed: Callback to be called when the widget is toggled.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateRadiobox(WidgetCallback changed) = 0;
 
@@ -796,9 +804,9 @@ By default the spinbox has minimum and maximum values of 0.0 and 100.0, these ca
 :param int decimalPlaces: The number of decimal places to display when showing the number.
 :param float step: The step value to apply in each direction when clicking up or down.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
-  virtual QWidget *CreateSpinbox(int decimalPlaces, double step) = 0;
+  virtual QWidget *CreateSpinbox(int32_t decimalPlaces, double step) = 0;
 
   DOCUMENT(R"(Set the minimum and maximum values allowed in the spinbox. If another type of widget
 is passed nothing will happen.
@@ -834,7 +842,7 @@ happen.
   multi-line text box.
 :param WidgetCallback changed: Callback to be called when the text in the textbox is changed.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateTextBox(bool singleLine, WidgetCallback changed) = 0;
 
@@ -848,7 +856,7 @@ When created there are no pre-defined entries in the drop-down section. This can
 :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.
 :return: The handle to the newly created widget.
-:rtype: ``QWidget``
+:rtype: QWidget
 )");
   virtual QWidget *CreateComboBox(bool editable, WidgetCallback changed) = 0;
 
@@ -856,7 +864,7 @@ When created there are no pre-defined entries in the drop-down section. This can
 passed nothing will happen.
 
 :param QWidget combo: The combo box.
-:param ``list`` of ``str`` options: The new options for the combo box.
+:param List[str] options: The new options for the combo box.
 )");
   virtual void SetComboOptions(QWidget *combo, const rdcarray<rdcstr> &options) = 0;
 
@@ -893,7 +901,7 @@ struct IExtensionManager
   DOCUMENT(R"(Retrieve a list of installed extensions.
 
 :return: The list of installed extensions.
-:rtype: ``list`` of :class:`ExtensionMetadata`.
+:rtype: List[ExtensionMetadata]
 )");
   virtual rdcarray<ExtensionMetadata> GetInstalledExtensions() = 0;
 
@@ -924,11 +932,10 @@ struct IExtensionManager
   with a child may not receive callbacks at the correct times.
 
 :param WindowMenu base: The base menu to add the item to.
-:param list 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, or two entries
-  if ``base`` is :data:`WindowMenu.NewMenu`.
-:param callback: The function to callback when the menu item is selected.
-:type method: :func:`ExtensionCallback`
+: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, or two
+  entries if ``base`` is :data:`WindowMenu.NewMenu`.
+:param ExtensionCallback callback: The function to callback when the menu item is selected.
 )");
   virtual void RegisterWindowMenu(WindowMenu base, const rdcarray<rdcstr> &submenus,
                                   ExtensionCallback callback) = 0;
@@ -941,10 +948,9 @@ struct IExtensionManager
   with a child may not receive callbacks at the correct times.
 
 :param PanelMenu base: The panel to add the item to.
-:param list 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 callback: The function to callback when the menu item is selected.
-:type method: :func:`ExtensionCallback`
+: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.
 )");
   virtual void RegisterPanelMenu(PanelMenu base, const rdcarray<rdcstr> &submenus,
                                  ExtensionCallback callback) = 0;
@@ -957,10 +963,9 @@ struct IExtensionManager
   with a child may not receive callbacks at the correct times.
 
 :param ContextMenu base: The panel to add the item to.
-:param list 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 callback: The function to callback when the menu item is selected.
-:type method: :func:`ExtensionCallback`
+: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.
 )");
   virtual void RegisterContextMenu(ContextMenu base, const rdcarray<rdcstr> &submenus,
                                    ExtensionCallback callback) = 0;
@@ -993,7 +998,7 @@ struct IExtensionManager
   DOCUMENT(R"(Display an error message dialog.
 
 :param str text: The text of the dialog itself, required.
-:param list options: The buttons to display on the dialog.
+:param List[DialogButton] options: The buttons to display on the dialog.
 :param str title: The dialog title, optional.
 :return: The button that was clicked on.
 :rtype: DialogButton

qrenderdoc/Code/Interface/PersistantConfig.h

@@ -104,13 +104,13 @@ inline rdcstr ToolExecutable(KnownShaderTool tool)
   return "";
 }
 
-DOCUMENT(R"(Returns the expected default input :class:`ShaderEncoding` that a
+DOCUMENT(R"(Returns the expected default input :class:`~renderdoc.ShaderEncoding` that a
 :class:`KnownShaderTool` expects. This may not be accurate and may be configurable depending on the
 tool.
 
 :param KnownShaderTool tool: The tool to get the input encoding for.
 :return: The encoding that this tool expects as an input by default.
-:rtype: ShaderEncoding
+:rtype: renderdoc.ShaderEncoding
 )");
 inline ShaderEncoding ToolInput(KnownShaderTool tool)
 {
@@ -128,13 +128,13 @@ inline ShaderEncoding ToolInput(KnownShaderTool tool)
   return ShaderEncoding::Unknown;
 }
 
-DOCUMENT(R"(Returns the expected default output :class:`ShaderEncoding` that a
+DOCUMENT(R"(Returns the expected default output :class:`~renderdoc.ShaderEncoding` that a
 :class:`KnownShaderTool` produces. This may not be accurate and may be configurable depending on the
 tool.
 
 :param KnownShaderTool tool: The tool to get the output encoding for.
 :return: The encoding that this tool produces as an output by default.
-:rtype: ShaderEncoding
+:rtype: renderdoc.ShaderEncoding
 )");
 inline ShaderEncoding ToolOutput(KnownShaderTool tool)
 {
@@ -210,21 +210,21 @@ struct ShaderProcessingTool
   DOCUMENT(R"(Return the default arguments used when invoking this tool
 
 :return: The arguments specified for this tool.
-:rtype: ``str``
+:rtype: str
 )");
   rdcstr DefaultArguments() const;
 
   DOCUMENT(R"(Runs this program to disassemble a given shader reflection.
 
 :param QWidget window: A handle to the window to use when showing a progress bar or error messages.
-:param ~renderdoc.ShaderReflection shader: The shader to disassemble.
+:param renderdoc.ShaderReflection shader: The shader to disassemble.
 :param str args: arguments to pass to the tool. The default arguments can be obtained using
   :meth:`DefaultArguments` which can then be customised as desired. Passing an empty string uses the
   default arguments.
 :return: The result of running the tool.
 :rtype: ShaderToolOutput
 )");
-  ShaderToolOutput DisassembleShader(QWidget *window, const ShaderReflection *reflection,
+  ShaderToolOutput DisassembleShader(QWidget *window, const ShaderReflection *shader,
                                      rdcstr args) const;
 
   DOCUMENT(R"(Runs this program to disassemble a given shader source.
@@ -232,7 +232,7 @@ struct ShaderProcessingTool
 :param QWidget window: A handle to the window to use when showing a progress bar or error messages.
 :param str source: The source code, preprocessed into a single file.
 :param str entryPoint: The name of the entry point in the shader to compile.
-:param ~renderdoc.ShaderStage stage: The pipeline stage that this shader represents.
+:param renderdoc.ShaderStage stage: The pipeline stage that this shader represents.
 :param str args: arguments to pass to the tool. The default arguments can be obtained using
   :meth:`DefaultArguments` which can then be customised as desired. Passing an empty string uses the
   default arguments.
@@ -284,7 +284,7 @@ struct BugReport
   DOCUMENT(R"(Gets the URL for this report.
 
 :return: The URL to the report.
-:rtype: ``str``
+:rtype: str
 )");
   rdcstr URL() const;
 };
@@ -438,8 +438,9 @@ DECLARE_REFLECTION_ENUM(TimeUnit);
 
 DOCUMENT(R"(Gets the suffix for a time unit.
 
+:param TimeUnit unit: The unit to get a suffix for.
 :return: The one or two character suffix.
-:rtype: ``str``
+:rtype: str
 )");
 inline rdcstr UnitSuffix(TimeUnit unit)
 {
@@ -461,7 +462,7 @@ not then it's added to the end
 
 As the name suggests, this is used for tracking a 'recent file' list.
 
-:param list recentList: A ``list`` of ``str`` that is mutated by the function.
+:param List[str] recentList: The list that is mutated by the function.
 :param str file: The file to add to the list.
 )");
 void AddRecentFile(rdcarray<rdcstr> &recentList, const rdcstr &file);
@@ -471,7 +472,7 @@ present then the list is not modified.
 
 As the name suggests, this is used for tracking a 'recent file' list.
 
-:param list recentList: A ``list`` of ``str`` that is mutated by the function.
+:param List[str] recentList: The list that is mutated by the function.
 :param str file: The file to remove from the list.
 )");
 void RemoveRecentFile(rdcarray<rdcstr> &recentList, const rdcstr &file);
@@ -502,7 +503,9 @@ For more information about some of these settings that are user-facing see
 
 .. data:: RecentCaptureFiles
 
-  A ``list`` of ``str`` with the recently opened capture files.
+  The recently opened capture files.
+
+  :type: List[str]
 
 .. data:: LastCapturePath
 
@@ -515,7 +518,9 @@ For more information about some of these settings that are user-facing see
 
 .. data:: RecentCaptureSettings
 
-  A ``list`` of ``str`` with the recently opened capture settings files.
+  The recently opened capture settings files.
+
+  :type: List[str]
 
 .. data:: TemporaryCaptureDirectory
 
@@ -790,13 +795,14 @@ public:
   DOCUMENT(R"(Returns a list of all remote hosts.
 
 :return: The remote host list
-:rtype: ``list`` of ``RemoteHost``
+:rtype: List[RemoteHost]
 )");
   rdcarray<RemoteHost> GetRemoteHosts();
   DOCUMENT(R"(Look up a remote host by hostname.
 
+:param str hostname: The hostname to look up
 :return: The remote host for the given hostname, or an invalid ``RemoteHost`` if no such exists.
-:rtype: ``RemoteHost``
+:rtype: RemoteHost
 )");
   RemoteHost GetRemoteHost(const rdcstr &hostname);
 
@@ -824,7 +830,7 @@ not recommended that you call this function manually.
 
 :param str filename: The filename to load from
 :return: A boolean status if the load was successful.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool Load(const rdcstr &filename);
 
@@ -832,7 +838,7 @@ not recommended that you call this function manually.
 propagated and will not be forgotten in the case of crash or otherwise unexpected exit.
 
 :return: A boolean status if the save was successful.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool Save();
 
@@ -853,10 +859,9 @@ loading. It can explicitly save and close before relaunching.
 Changing the style after the application has started may not properly update everything, so to be
 sure the new style is applied, the application should be restarted.
 
-:param str name: The name of the setting.
 :return: ``True`` if the style was set successfully, ``False`` if there was a problem e.g. the value
   of :data:`UIStyle` was unrecognised or empty.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool SetStyle();
 

qrenderdoc/Code/Interface/RemoteHost.h

@@ -59,34 +59,68 @@ public:
   DOCUMENT(
       "Ping the host to check current status - if the server is running, connection status, etc.");
   void CheckStatus();
-  DOCUMENT(
-      "Runs the command specified in :data:`runCommand`. Returns :class:`ReplayStatus` which "
-      "indicates success or the type of failure.");
+
+  DOCUMENT(R"(Runs the command specified in :data:`runCommand`. Returns
+:class:`~renderdoc.ReplayStatus` which indicates success or the type of failure.
+
+:return: The result from launching the remote server.
+:rtype: renderdoc.ReplayStatus
+)");
   ReplayStatus Launch();
 
-  DOCUMENT("``True`` if a remote server is currently running on this host.");
+  DOCUMENT(R"(
+:return: ``True`` if a remote server is currently running on this host.
+:rtype: bool
+)");
   bool IsServerRunning() const;
-  DOCUMENT("``True`` if an active connection exists to this remote server.");
+
+  DOCUMENT(R"(
+:return: ``True`` if an active connection exists to this remote server.
+:rtype: bool
+)");
   bool IsConnected() const;
-  DOCUMENT("``True`` if someone else is currently connected to this server.");
+
+  DOCUMENT(R"(
+:return: ``True`` if someone else is currently connected to this server.
+:rtype: bool
+)");
   bool IsBusy() const;
-  DOCUMENT("``True`` if there is a code version mismatch with this server.");
+
+  DOCUMENT(R"(
+:return: ``True`` if there is a code version mismatch with this server.
+:rtype: bool
+)");
   bool IsVersionMismatch() const;
 
-  DOCUMENT("The hostname of this host.");
-  const rdcstr &Hostname() const { return m_hostname; }
-  DOCUMENT("The friendly name for this host, if available (if empty, the Hostname is used).");
+  DOCUMENT(R"(
+:return: The hostname of this host.
+:rtype: str
+)");
+  rdcstr Hostname() const { return m_hostname; }
+  DOCUMENT(R"(
+:return: The friendly name for this host, if available (if empty, the Hostname is used).
+:rtype: str
+)");
   rdcstr FriendlyName() const;
-  DOCUMENT("The command to run locally to try to launch the server remotely.");
+
+  DOCUMENT(R"(
+:return: The command to run locally to try to launch the server remotely.
+:rtype: str
+)");
   rdcstr RunCommand() const;
+
   DOCUMENT(R"(Sets the run command. See :meth:`RunCommand`.
 
 :param str cmd: The new command to set.
 )");
   void SetRunCommand(const rdcstr &cmd);
 
-  DOCUMENT("The last folder browsed to on this host, to provide a reasonable default path.");
+  DOCUMENT(R"(
+:return: The last folder browsed to on this host, to provide a reasonable default path.
+:rtype: str
+)");
   rdcstr LastCapturePath() const;
+
   DOCUMENT(R"(Sets the last folder browsed to. See :meth:`LastCapturePath`.
 
 :param str path: The new path to set.
@@ -97,25 +131,35 @@ public:
 
 :return: The status of opening the capture, whether success or failure, and a :class:`RemoteServer`
   instance if it were successful
-:rtype: ``pair`` of ReplayStatus and RemoteServer
+:rtype: Tuple[renderdoc.ReplayStatus, renderdoc.RemoteServer]
 )");
   ReplayStatus Connect(IRemoteServer **server);
 
-  DOCUMENT(
-      "The :class:`DeviceProtocolController` for this host, or ``None`` if no protocol is in use");
+  DOCUMENT(R"(
+:return: The :class:`~renderdoc.DeviceProtocolController` for this host, or ``None`` if no protocol
+  is in use
+:rtype: renderdoc.DeviceProtocolController
+)");
   IDeviceProtocolController *Protocol() const { return m_protocol; }
   DOCUMENT(R"(
-Returns the name to display for this host in the UI, either :meth:`FriendlyName` if it is valid, or
+:return: The name to display for this host in the UI, either :meth:`FriendlyName` if it is valid, or
 :meth:`Hostname` if not.
+:rtype: str
 )");
   rdcstr Name() const
   {
     rdcstr friendlyName = FriendlyName();
     return !friendlyName.isEmpty() ? friendlyName : m_hostname;
   }
-  DOCUMENT("Returns ``True`` if this host represents the special localhost device.");
+
+  DOCUMENT(R"(
+:return: Returns ``True`` if this host represents the special localhost device.
+:rtype: bool
+)");
   bool IsLocalhost() const { return m_hostname == "localhost"; }
-  DOCUMENT("Returns ``True`` if this host represents a valid remote host.");
+  DOCUMENT(R"(Returns ``True`` if this host represents a valid remote host.
+:rtype: bool
+)");
   bool IsValid() const { return m_data && !m_hostname.isEmpty(); }
 private:
   // this is immutable and is used as a key to look up data, it's always valid as RemoteHost objects

qrenderdoc/Code/MiniQtHelper.cpp

@@ -136,7 +136,7 @@ QWidget *MiniQtHelper::GetParent(QWidget *widget)
   return widget->parentWidget();
 }
 
-int MiniQtHelper::GetNumChildren(QWidget *widget)
+int32_t MiniQtHelper::GetNumChildren(QWidget *widget)
 {
   if(!widget)
     return 0;
@@ -148,7 +148,7 @@ int MiniQtHelper::GetNumChildren(QWidget *widget)
   return layout->count();
 }
 
-QWidget *MiniQtHelper::GetChild(QWidget *parent, int index)
+QWidget *MiniQtHelper::GetChild(QWidget *parent, int32_t index)
 {
   if(!parent)
     return NULL;
@@ -249,8 +249,8 @@ void MiniQtHelper::ClearContainedWidgets(QWidget *parent)
   }
 }
 
-void MiniQtHelper::AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan,
-                                 int columnSpan)
+void MiniQtHelper::AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child,
+                                 int32_t rowSpan, int32_t columnSpan)
 {
   if(!parent || !child)
     return;
@@ -282,7 +282,7 @@ void MiniQtHelper::AddWidget(QWidget *parent, QWidget *child)
   box->addWidget(child);
 }
 
-void MiniQtHelper::InsertWidget(QWidget *parent, int index, QWidget *child)
+void MiniQtHelper::InsertWidget(QWidget *parent, int32_t index, QWidget *child)
 {
   if(!parent)
     return;
@@ -384,7 +384,7 @@ rdcstr MiniQtHelper::GetWidgetText(QWidget *widget)
   return widget->windowTitle();
 }
 
-void MiniQtHelper::SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold,
+void MiniQtHelper::SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold,
                                  bool italic)
 {
   if(!widget)
@@ -555,7 +555,7 @@ bool MiniQtHelper::IsWidgetChecked(QWidget *checkableWidget)
   return false;
 }
 
-QWidget *MiniQtHelper::CreateSpinbox(int decimalPlaces, double step)
+QWidget *MiniQtHelper::CreateSpinbox(int32_t decimalPlaces, double step)
 {
   RDDoubleSpinBox *ret = new RDDoubleSpinBox();
   ret->setSingleStep(step);

qrenderdoc/Code/MiniQtHelper.h

@@ -46,8 +46,8 @@ public:
   rdcstr GetWidgetType(QWidget *widget) override;
   QWidget *FindChildByName(QWidget *parent, const rdcstr &name) override;
   QWidget *GetParent(QWidget *widget) override;
-  int GetNumChildren(QWidget *widget) override;
-  QWidget *GetChild(QWidget *parent, int index) override;
+  int32_t GetNumChildren(QWidget *widget) override;
+  QWidget *GetChild(QWidget *parent, int32_t index) override;
   void DestroyWidget(QWidget *widget) override;
 
   // dialogs
@@ -63,17 +63,17 @@ public:
   QWidget *CreateSpacer(bool horizontal) override;
 
   void ClearContainedWidgets(QWidget *parent) override;
-  void AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan,
-                     int columnSpan) override;
+  void AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child, int32_t rowSpan,
+                     int32_t columnSpan) override;
   void AddWidget(QWidget *parent, QWidget *child) override;
-  void InsertWidget(QWidget *parent, int index, QWidget *child) override;
+  void InsertWidget(QWidget *parent, int32_t index, QWidget *child) override;
 
   // widget manipulation
 
   void SetWidgetText(QWidget *widget, const rdcstr &text) override;
   rdcstr GetWidgetText(QWidget *widget) override;
 
-  void SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold,
+  void SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold,
                      bool italic) override;
 
   void SetWidgetEnabled(QWidget *widget, bool enabled) override;
@@ -102,7 +102,7 @@ public:
   void SetWidgetChecked(QWidget *checkableWidget, bool checked) override;
   bool IsWidgetChecked(QWidget *checkableWidget) override;
 
-  QWidget *CreateSpinbox(int decimalPlaces, double step) override;
+  QWidget *CreateSpinbox(int32_t decimalPlaces, double step) override;
 
   void SetSpinboxBounds(QWidget *spinbox, double minVal, double maxVal) override;
   void SetSpinboxValue(QWidget *spinbox, double value) override;

qrenderdoc/Code/pyrenderdoc/renderdoc.i

@@ -268,7 +268,7 @@ TEMPLATE_ARRAY_DECLARE(rdcarray);
 the built-in repr() function but it iterates over struct members and prints them out, where normally
 repr() would stop and say something like 'Swig Object of type ...'.
 
-:param Any object: The object to dump
+:param Any obj: The object to dump
 :return: The string representation of the object.
 :rtype: str
 )";
@@ -284,6 +284,9 @@ extern "C" PyObject *RENDERDOC_DumpObject(PyObject *obj);
 %extend SDObject {
   %feature("docstring") R"(Interprets the object as an integer and returns its value.
 Invalid if the object is not actually an integer.
+
+:return: The interpreted integer.
+:rtype: int
 )";
   PyObject *AsInt()
   {
@@ -295,11 +298,17 @@ Invalid if the object is not actually an integer.
   
   %feature("docstring") R"(Interprets the object as a floating point number and returns its value.
 Invalid if the object is not actually a floating point number.
+
+:return: The interpreted float.
+:rtype: float
 )";
   PyObject *AsFloat() { return ConvertToPy($self->data.basic.d); }
   
   %feature("docstring") R"(Interprets the object as a string and returns its value.
 Invalid if the object is not actually a string.
+
+:return: The interpreted string.
+:rtype: str
 )";
   PyObject *AsString() { return ConvertToPy($self->data.str); }
 }

qrenderdoc/Windows/BufferViewer.cpp

@@ -3386,13 +3386,13 @@ void BufferViewer::ScrollToColumn(RDTableView *view, int column)
   view->verticalScrollBar()->setValue(vs);
 }
 
-void BufferViewer::SetCurrentInstance(int instance)
+void BufferViewer::SetCurrentInstance(int32_t instance)
 {
   if(ui->instance->isVisible() && ui->instance->isEnabled())
     ui->instance->setValue(instance);
 }
 
-void BufferViewer::SetCurrentView(int view)
+void BufferViewer::SetCurrentView(int32_t view)
 {
   if(ui->viewIndex->isVisible() && ui->viewIndex->isEnabled())
     ui->viewIndex->setValue(view);
@@ -3440,7 +3440,7 @@ void BufferViewer::ViewTexture(ResourceId id, const Subresource &sub, const rdcs
   processFormat(format);
 }
 
-void BufferViewer::ScrollToRow(int row, MeshDataStage stage)
+void BufferViewer::ScrollToRow(int32_t row, MeshDataStage stage)
 {
   ScrollToRow(tableForStage(stage), row);
 
@@ -3451,7 +3451,7 @@ void BufferViewer::ScrollToRow(int row, MeshDataStage stage)
     ui->rowOffset->setValue(row);
 }
 
-void BufferViewer::ScrollToColumn(int column, MeshDataStage stage)
+void BufferViewer::ScrollToColumn(int32_t column, MeshDataStage stage)
 {
   ScrollToColumn(tableForStage(stage), column);
 

qrenderdoc/Windows/BufferViewer.h

@@ -84,10 +84,10 @@ public:
 
   // IBufferViewer
   QWidget *Widget() override { return this; }
-  void ScrollToRow(int row, MeshDataStage stage = MeshDataStage::VSIn) override;
-  void ScrollToColumn(int column, MeshDataStage stage = MeshDataStage::VSIn) override;
-  void SetCurrentInstance(int instance) override;
-  void SetCurrentView(int view) override;
+  void ScrollToRow(int32_t row, MeshDataStage stage = MeshDataStage::VSIn) override;
+  void ScrollToColumn(int32_t column, MeshDataStage stage = MeshDataStage::VSIn) override;
+  void SetCurrentInstance(int32_t instance) override;
+  void SetCurrentView(int32_t view) override;
 
   // ICaptureViewer
   void OnCaptureLoaded() override;

qrenderdoc/Windows/PythonShell.cpp

@@ -122,11 +122,11 @@ struct MiniQtInvoker : ObjectForwarder<IMiniQtHelper>
   {
     return InvokeRetFunction<QWidget *>(&IMiniQtHelper::GetParent, widget);
   }
-  int GetNumChildren(QWidget *widget)
+  int32_t GetNumChildren(QWidget *widget)
   {
-    return InvokeRetFunction<int>(&IMiniQtHelper::GetNumChildren, widget);
+    return InvokeRetFunction<int32_t>(&IMiniQtHelper::GetNumChildren, widget);
   }
-  QWidget *GetChild(QWidget *parent, int index)
+  QWidget *GetChild(QWidget *parent, int32_t index)
   {
     return InvokeRetFunction<QWidget *>(&IMiniQtHelper::GetChild, parent, index);
   }
@@ -164,7 +164,8 @@ struct MiniQtInvoker : ObjectForwarder<IMiniQtHelper>
   {
     InvokeVoidFunction(&IMiniQtHelper::ClearContainedWidgets, parent);
   }
-  void AddGridWidget(QWidget *parent, int row, int column, QWidget *child, int rowSpan, int columnSpan)
+  void AddGridWidget(QWidget *parent, int32_t row, int32_t column, QWidget *child, int32_t rowSpan,
+                     int32_t columnSpan)
   {
     InvokeVoidFunction(&IMiniQtHelper::AddGridWidget, parent, row, column, child, rowSpan,
                        columnSpan);
@@ -173,7 +174,7 @@ struct MiniQtInvoker : ObjectForwarder<IMiniQtHelper>
   {
     InvokeVoidFunction(&IMiniQtHelper::AddWidget, parent, child);
   }
-  void InsertWidget(QWidget *parent, int index, QWidget *child)
+  void InsertWidget(QWidget *parent, int32_t index, QWidget *child)
   {
     InvokeVoidFunction(&IMiniQtHelper::InsertWidget, parent, index, child);
   }
@@ -189,7 +190,7 @@ struct MiniQtInvoker : ObjectForwarder<IMiniQtHelper>
     return InvokeRetFunction<rdcstr>(&IMiniQtHelper::GetWidgetText, widget);
   }
 
-  void SetWidgetFont(QWidget *widget, const rdcstr &font, int fontSize, bool bold, bool italic)
+  void SetWidgetFont(QWidget *widget, const rdcstr &font, int32_t fontSize, bool bold, bool italic)
   {
     InvokeVoidFunction(&IMiniQtHelper::SetWidgetFont, widget, font, fontSize, bold, italic);
   }
@@ -260,7 +261,7 @@ struct MiniQtInvoker : ObjectForwarder<IMiniQtHelper>
     return InvokeRetFunction<bool>(&IMiniQtHelper::IsWidgetChecked, checkableWidget);
   }
 
-  QWidget *CreateSpinbox(int decimalPlaces, double step)
+  QWidget *CreateSpinbox(int32_t decimalPlaces, double step)
   {
     return InvokeRetFunction<QWidget *>(&IMiniQtHelper::CreateSpinbox, decimalPlaces, step);
   }
@@ -450,7 +451,7 @@ struct CaptureContextInvoker : ObjectForwarder<ICaptureContext>
   {
     return m_Obj.HasResourceCustomName(id);
   }
-  virtual int ResourceNameCacheID() override { return m_Obj.ResourceNameCacheID(); }
+  virtual int32_t ResourceNameCacheID() override { return m_Obj.ResourceNameCacheID(); }
   virtual TextureDescription *GetTexture(ResourceId id) override { return m_Obj.GetTexture(id); }
   virtual const rdcarray<TextureDescription> &GetTextures() override { return m_Obj.GetTextures(); }
   virtual BufferDescription *GetBuffer(ResourceId id) override { return m_Obj.GetBuffer(id); }
@@ -467,7 +468,7 @@ struct CaptureContextInvoker : ObjectForwarder<ICaptureContext>
   virtual const SDFile &GetStructuredFile() override { return m_Obj.GetStructuredFile(); }
   virtual WindowingSystem CurWindowingSystem() override { return m_Obj.CurWindowingSystem(); }
   virtual const rdcarray<DebugMessage> &DebugMessages() override { return m_Obj.DebugMessages(); }
-  virtual int UnreadMessageCount() override { return m_Obj.UnreadMessageCount(); }
+  virtual int32_t UnreadMessageCount() override { return m_Obj.UnreadMessageCount(); }
   virtual void MarkMessagesRead() override { return m_Obj.MarkMessagesRead(); }
   virtual rdcstr GetNotes(const rdcstr &key) override { return m_Obj.GetNotes(key); }
   virtual rdcarray<EventBookmark> GetBookmarks() override { return m_Obj.GetBookmarks(); }
@@ -775,7 +776,7 @@ struct CaptureContextInvoker : ObjectForwarder<ICaptureContext>
                                                          stage, slot, idx);
   }
 
-  virtual IPixelHistoryView *ViewPixelHistory(ResourceId texID, int x, int y,
+  virtual IPixelHistoryView *ViewPixelHistory(ResourceId texID, uint32_t x, uint32_t y,
                                               const TextureDisplay &display) override
   {
     return InvokeRetFunction<IPixelHistoryView *>(&ICaptureContext::ViewPixelHistory, texID, x, y,

qrenderdoc/Windows/ShaderViewer.cpp

@@ -3916,7 +3916,7 @@ void ShaderViewer::SetCurrentStep(uint32_t step)
   updateDebugState();
 }
 
-void ShaderViewer::ToggleBreakpoint(int instruction)
+void ShaderViewer::ToggleBreakpoint(int32_t instruction)
 {
   if(!m_Trace || m_States.empty())
     return;

qrenderdoc/Windows/ShaderViewer.h

@@ -120,7 +120,7 @@ public:
   virtual uint32_t CurrentStep() override;
   virtual void SetCurrentStep(uint32_t step) override;
 
-  virtual void ToggleBreakpoint(int instruction = -1) override;
+  virtual void ToggleBreakpoint(int32_t instruction = -1) override;
 
   virtual void ShowErrors(const rdcstr &errors) override;
 

qrenderdoc/Windows/TextureViewer.cpp

@@ -2143,7 +2143,7 @@ void TextureViewer::SetSelectedSubresource(Subresource sub)
     ui->sliceFace->setCurrentIndex(qMin(sub.slice, tex->arraysize - 1));
 }
 
-void TextureViewer::GotoLocation(int x, int y)
+void TextureViewer::GotoLocation(uint32_t x, uint32_t y)
 {
   if(!m_Ctx.IsCaptureLoaded())
     return;
@@ -2153,8 +2153,8 @@ void TextureViewer::GotoLocation(int x, int y)
   if(tex == NULL)
     return;
 
-  x = qMin(x << m_TexDisplay.subresource.mip, int(tex->width - 1));
-  y = qMin(y << m_TexDisplay.subresource.mip, int(tex->height - 1));
+  x = qMin(x << m_TexDisplay.subresource.mip, uint32_t(tex->width - 1));
+  y = qMin(y << m_TexDisplay.subresource.mip, uint32_t(tex->height - 1));
 
   m_PickedPoint = QPoint(x, y);
 

qrenderdoc/Windows/TextureViewer.h

@@ -143,7 +143,7 @@ public:
 
   Subresource GetSelectedSubresource() override;
   void SetSelectedSubresource(Subresource sub) override;
-  void GotoLocation(int x, int y) override;
+  void GotoLocation(uint32_t x, uint32_t y) override;
   DebugOverlay GetTextureOverlay() override;
   void SetTextureOverlay(DebugOverlay overlay) override;
 

qrenderdoc/Windows/TimelineBar.h

@@ -37,7 +37,7 @@ public:
 
   QSize minimumSizeHint() const override;
 
-  // IStatisticsViewer
+  // ITimelineBar
   QWidget *Widget() override { return this; }
   void HighlightResourceUsage(ResourceId id) override;
   void HighlightHistory(ResourceId id, const rdcarray<PixelModification> &history) override;

renderdoc/api/replay/capture_options.h

@@ -47,7 +47,7 @@ struct CaptureOptions
   DOCUMENT(R"(Encode the current options to a string suitable for passing around between processes.
 
 :return: The encoded string, suitable for passing to :meth:`DecodeFromString`.
-:rtype: ``str``
+:rtype: str
 )");
   inline rdcstr EncodeAsString() const
   {
@@ -63,16 +63,21 @@ struct CaptureOptions
     return optstr;
   }
 
-  DOCUMENT("Decode the options from a string, as returned by :meth:`EncodeAsString`.");
-  inline void DecodeFromString(const rdcstr &str)
+  DOCUMENT(R"(Decode the options from a string, as returned by :meth:`EncodeAsString`. Updates this
+object in place.
+
+:param str encoded: The encoded string, as returned by :meth:`EncodeAsString`.
+)");
+  inline void DecodeFromString(const rdcstr &encoded)
   {
-    if(str.size() < sizeof(CaptureOptions))
+    if(encoded.size() < sizeof(CaptureOptions))
       return;
 
     // serialise from string with two chars per byte
     byte *b = (byte *)this;
     for(size_t i = 0; i < sizeof(CaptureOptions); i++)
-      *(b++) = byte(((byte(str[i * 2 + 0] - 'a') & 0xf) << 4) | (byte(str[i * 2 + 1] - 'a') & 0xf));
+      *(b++) = byte(((byte(encoded[i * 2 + 0] - 'a') & 0xf) << 4) |
+                    (byte(encoded[i * 2 + 1] - 'a') & 0xf));
   }
 
   DOCUMENT(R"(Allow the application to enable vsync.

renderdoc/api/replay/d3d11_pipestate.h

@@ -343,7 +343,7 @@ struct Sampler
   DOCUMENT(R"(Check if the border color is used in this D3D11 sampler.
 
 :return: ``True`` if the border color is used, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool UseBorder() const
   {

renderdoc/api/replay/d3d12_pipestate.h

@@ -366,7 +366,7 @@ struct Sampler
   DOCUMENT(R"(Check if the border color is used in this D3D12 sampler.
 
 :return: ``True`` if the border color is used, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool UseBorder() const
   {

renderdoc/api/replay/data_types.h

@@ -186,7 +186,7 @@ struct ResourceFormat
 
   bool operator!=(const ResourceFormat &r) const { return !(*this == r); }
   DOCUMENT(R"(:return: The name of the format.
-:rtype: ``str``
+:rtype: str
 )");
   rdcstr Name() const
   {
@@ -196,7 +196,7 @@ struct ResourceFormat
   }
 
   DOCUMENT(R"(:return: ``True`` if the ``ResourceFormat`` is a 'special' non-regular type.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool Special() const { return type != ResourceFormatType::Regular; }
   DOCUMENT(R"(The :class:`ResourceFormatType` of this format. If the value is not
@@ -212,13 +212,13 @@ struct ResourceFormat
   With BGRA order this means blue is in the first byte/lowest bits, but alpha is still always
   expected in the last byte/uppermost bits.
 
-:rtype: ``bool``
+:rtype: bool
 )");
   bool BGRAOrder() const { return (flags & ResourceFormat_BGRA) != 0; }
   DOCUMENT(R"(Equivalent to checking if :data:`compType` is :data:`CompType.UNormSRGB`
 
 :return: ``True`` if the components are SRGB corrected on read and write.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool SRGBCorrected() const { return compType == CompType::UNormSRGB; }
   DOCUMENT(R"(Get the subsampling rate for a YUV format. Only valid when :data:`type` is
@@ -227,7 +227,7 @@ a YUV format like :attr:`ResourceFormatType.YUV8`.
 For other formats, 0 is returned.
 
 :return: The subsampling rate, e.g. 444 for 4:4:4 or 420 for 4:2:0
-:rtype: ``int``
+:rtype: int
 )");
   uint32_t YUVSubsampling() const
   {
@@ -246,7 +246,7 @@ a YUV format like :attr:`ResourceFormatType.YUV8`.
 For other formats, 1 is returned.
 
 :return: The number of planes
-:rtype: ``int``
+:rtype: int
 )");
   uint32_t YUVPlaneCount() const
   {
@@ -273,7 +273,7 @@ For other formats, 1 is returned.
 
 The value should be e.g. 444 for 4:4:4 or 422 for 4:2:2. Invalid values will result in 0 being set.
 
-:param int subsample: The new subsampling rate.
+:param int subsampling: The new subsampling rate.
 )");
   void SetYUVSubsampling(uint32_t subsampling)
   {
@@ -1772,7 +1772,10 @@ struct ModificationValue
   DOCUMENT("The stencil output, or ``-1`` if not available.");
   int32_t stencil;
 
-  DOCUMENT("Returns whether or not this modification value is valid.");
+  DOCUMENT(R"(
+:return: Returns whether or not this modification value is valid.
+:rtype: bool
+)");
   bool IsValid() const { return col.uintValue[0] != 0xdeadbeef || col.uintValue[1] != 0xdeadf00d; }
   DOCUMENT("Sets this modification value to be invalid.");
   void SetInvalid()
@@ -1893,7 +1896,7 @@ pixel.
   DOCUMENT(R"(Determine if this fragment passed all tests and wrote to the texture.
 
 :return: ``True`` if it passed all tests, ``False`` if it failed any.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool Passed() const
   {

renderdoc/api/replay/gl_pipestate.h

@@ -353,7 +353,7 @@ struct Sampler
   DOCUMENT(R"(Check if the border color is used in this OpenGL sampler.
 
 :return: ``True`` if the border color is used, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool UseBorder() const
   {

renderdoc/api/replay/pipestate.h

@@ -59,7 +59,7 @@ public:
   DOCUMENT(R"(Determines whether or not a capture is currently loaded.
 
 :return: A boolean indicating if a capture is currently loaded.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsCaptureLoaded() const
   {
@@ -69,7 +69,7 @@ public:
   DOCUMENT(R"(Determines whether or not a D3D11 capture is currently loaded.
 
 :return: A boolean indicating if a D3D11 capture is currently loaded.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsCaptureD3D11() const
   {
@@ -79,7 +79,7 @@ public:
   DOCUMENT(R"(Determines whether or not a D3D12 capture is currently loaded.
 
 :return: A boolean indicating if a D3D12 capture is currently loaded.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsCaptureD3D12() const
   {
@@ -89,7 +89,7 @@ public:
   DOCUMENT(R"(Determines whether or not an OpenGL capture is currently loaded.
 
 :return: A boolean indicating if an OpenGL capture is currently loaded.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsCaptureGL() const
   {
@@ -99,7 +99,7 @@ public:
   DOCUMENT(R"(Determines whether or not a Vulkan capture is currently loaded.
 
 :return: A boolean indicating if a Vulkan capture is currently loaded.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsCaptureVK() const
   {
@@ -111,7 +111,7 @@ public:
   DOCUMENT(R"(Determines whether or not tessellation is currently enabled.
 
 :return: A boolean indicating if tessellation is currently enabled.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsTessellationEnabled() const
   {
@@ -133,13 +133,16 @@ public:
     return false;
   }
 
-  DOCUMENT("Returns the number of views being broadcast to simultaneously during rendering.");
+  DOCUMENT(R"(
+:return: The number of views being broadcast to simultaneously during rendering.
+:rtype: int
+)");
   uint32_t MultiviewBroadcastCount() const;
 
   DOCUMENT(R"(Determines whether or not the current capture supports binding arrays of resources.
 
 :return: A boolean indicating if binding arrays of resources is supported.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool SupportsResourceArrays() const
   {
@@ -148,7 +151,7 @@ public:
   DOCUMENT(R"(Determines whether or not the current capture uses explicit barriers.
 
 :return: A boolean indicating if explicit barriers are used.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool SupportsBarriers() const { return IsCaptureLoaded() && (IsCaptureVK() || IsCaptureD3D12()); }
   DOCUMENT(R"(Determines whether or not the PostVS data is aligned in the typical fashion (ie.
@@ -158,7 +161,7 @@ requirements.
 
 :param MeshDataStage stage: The mesh data stage for the output data.
 :return: A boolean indicating if post-VS data is aligned.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool HasAlignedPostVSData(MeshDataStage stage) const
   {
@@ -166,8 +169,9 @@ requirements.
   }
   DOCUMENT(R"(For APIs that have explicit barriers, retrieves the current layout of a resource.
 
-:return: The name of the current resource layout.
-:rtype: ``str``
+:param ResourceId id: The ID of the resource to query for
+:return: The name of the current layout of the first subresource in the resource.
+:rtype: str
 )");
   rdcstr GetResourceLayout(ResourceId id) const;
 
@@ -175,7 +179,7 @@ requirements.
 
 :param ShaderStage stage: The shader stage to abbreviate.
 :return: The abbreviation of the stage.
-:rtype: ``str``
+:rtype: str
 )");
   rdcstr Abbrev(ShaderStage stage) const;
 
@@ -183,7 +187,7 @@ requirements.
 'OM' or 'FBO'.
 
 :return: The abbreviation of the output stage.
-:rtype: ``str``
+:rtype: str
 )");
   rdcstr OutputAbbrev() const;
 
@@ -193,7 +197,7 @@ requirements.
 :return: The viewport for the given index.
 :rtype: Viewport
 )");
-  Viewport GetViewport(int index) const;
+  Viewport GetViewport(uint32_t index) const;
 
   DOCUMENT(R"(Retrieves the scissor region for a given index.
 
@@ -201,7 +205,7 @@ requirements.
 :return: The scissor region for the given index.
 :rtype: Scissor
 )");
-  Scissor GetScissor(int index) const;
+  Scissor GetScissor(uint32_t index) const;
 
   DOCUMENT(R"(Retrieves the current bindpoint mapping for a shader stage.
 
@@ -219,7 +223,7 @@ This returns ``None`` if no shader is bound.
 
 :param ShaderStage stage: The shader stage to fetch.
 :return: The reflection data for the given shader.
-:rtype: :class:`ShaderReflection` or ``None``
+:rtype: ShaderReflection
 )");
   const ShaderReflection *GetShaderReflection(ShaderStage stage) const;
 
@@ -243,7 +247,7 @@ For some APIs that don't distinguish by entry point, this may be empty.
 
 :param ShaderStage stage: The shader stage to fetch.
 :return: The entry point name for the given shader.
-:rtype: ``str``
+:rtype: str
 )");
   rdcstr GetShaderEntryPoint(ShaderStage stage) const;
 
@@ -258,36 +262,35 @@ For some APIs that don't distinguish by entry point, this may be empty.
   DOCUMENT(R"(Retrieves the current index buffer binding.
 
 :return: A :class:`BoundVBuffer` with the index buffer details. The stride is always 0.
-:rtype: ``BoundVBuffer``
+:rtype: BoundVBuffer
 )");
   BoundVBuffer GetIBuffer() const;
 
   DOCUMENT(R"(Determines whether or not primitive restart is enabled.
 
 :return: A boolean indicating if primitive restart is enabled.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsStripRestartEnabled() const;
 
   DOCUMENT(R"(Retrieves the primitive restart index.
 
-:param int indexByteWidth: The width in bytes of the indices.
 :return: The index value that represents a strip restart not a real index.
-:rtype: ``int``
+:rtype: int
 )");
   uint32_t GetStripRestartIndex() const;
 
   DOCUMENT(R"(Retrieves the currently bound vertex buffers.
 
 :return: The list of bound vertex buffers.
-:rtype: ``list`` of :class:`BoundVBuffer`.
+:rtype: List[BoundVBuffer]
 )");
   rdcarray<BoundVBuffer> GetVBuffers() const;
 
   DOCUMENT(R"(Retrieves the currently specified vertex attributes.
 
 :return: The list of current vertex attributes.
-:rtype: ``list`` of :class:`VertexInputAttribute`.
+:rtype: List[VertexInputAttribute]
 )");
   rdcarray<VertexInputAttribute> GetVertexInputs() const;
 
@@ -308,7 +311,7 @@ For some APIs that don't distinguish by entry point, this may be empty.
 :param bool onlyUsed: Return only a subset of resources containing those actually used by the
   shader.
 :return: The currently bound read-only resources.
-:rtype: ``list`` of :class:`BoundResourceArray` entries
+:rtype: List[BoundResourceArray]
 )");
   rdcarray<BoundResourceArray> GetReadOnlyResources(ShaderStage stage, bool onlyUsed = false) const;
 
@@ -316,7 +319,7 @@ For some APIs that don't distinguish by entry point, this may be empty.
 
 :param ShaderStage stage: The shader stage to fetch from.
 :return: The currently bound sampler resources.
-:rtype: ``list`` of :class:`BoundResourceArray` entries
+:rtype: List[BoundResourceArray]
 )");
   rdcarray<BoundResourceArray> GetSamplers(ShaderStage stage) const;
 
@@ -326,7 +329,7 @@ For some APIs that don't distinguish by entry point, this may be empty.
 :param bool onlyUsed: Return only a subset of resources containing those actually used by the
   shader.
 :return: The currently bound read/write resources.
-:rtype: ``list`` of :class:`BoundResourceArray` entries
+:rtype: List[BoundResourceArray]
 )");
   rdcarray<BoundResourceArray> GetReadWriteResources(ShaderStage stage, bool onlyUsed = false) const;
 
@@ -340,21 +343,21 @@ For some APIs that don't distinguish by entry point, this may be empty.
   DOCUMENT(R"(Retrieves the resources bound to the color outputs.
 
 :return: The currently bound output targets.
-:rtype: ``list`` of :class:`BoundResource`.
+:rtype: List[BoundResource]
 )");
   rdcarray<BoundResource> GetOutputTargets() const;
 
   DOCUMENT(R"(Retrieves the current color blending states, per target.
 
 :return: The currently color blend states.
-:rtype: ``list`` of :class:`ColorBlend`.
+:rtype: List[ColorBlend]
 )");
   rdcarray<ColorBlend> GetColorBlends() const;
 
   DOCUMENT(R"(Determines whether or not independent blending is enabled.
 
 :return: A boolean indicating if independent blending is enabled.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool IsIndependentBlendingEnabled() const;
 

renderdoc/api/replay/pipestate.inl

@@ -168,25 +168,25 @@ const VKPipe::Shader &PipeState::GetVulkanStage(ShaderStage stage) const
   return m_Vulkan->computeShader;
 }
 
-Viewport PipeState::GetViewport(int index) const
+Viewport PipeState::GetViewport(uint32_t index) const
 {
   Viewport ret = {};
 
   if(IsCaptureLoaded())
   {
-    if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.count())
+    if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.size())
     {
       return m_D3D11->rasterizer.viewports[index];
     }
-    else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.count())
+    else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.size())
     {
       return m_D3D12->rasterizer.viewports[index];
     }
-    else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.count())
+    else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.size())
     {
       return m_GL->rasterizer.viewports[index];
     }
-    else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.count())
+    else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.size())
     {
       return m_Vulkan->viewportScissor.viewportScissors[index].vp;
     }
@@ -195,25 +195,25 @@ Viewport PipeState::GetViewport(int index) const
   return ret;
 }
 
-Scissor PipeState::GetScissor(int index) const
+Scissor PipeState::GetScissor(uint32_t index) const
 {
   Scissor ret = {};
 
   if(IsCaptureLoaded())
   {
-    if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.count())
+    if(IsCaptureD3D11() && index < m_D3D11->rasterizer.viewports.size())
     {
       return m_D3D11->rasterizer.scissors[index];
     }
-    else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.count())
+    else if(IsCaptureD3D12() && index < m_D3D12->rasterizer.viewports.size())
     {
       return m_D3D12->rasterizer.scissors[index];
     }
-    else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.count())
+    else if(IsCaptureGL() && index < m_GL->rasterizer.viewports.size())
     {
       return m_GL->rasterizer.scissors[index];
     }
-    else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.count())
+    else if(IsCaptureVK() && index < m_Vulkan->viewportScissor.viewportScissors.size())
     {
       return m_Vulkan->viewportScissor.viewportScissors[index].scissor;
     }

renderdoc/api/replay/renderdoc_replay.h

@@ -186,6 +186,9 @@ inline const WindowingData CreateAndroidWindowingData(ANativeWindow *window)
   return ret;
 }
 
+typedef void *NSView;
+typedef void *CALayer;
+
 DOCUMENT(R"(Create a :class:`WindowingData` for an metal/opengl-compatible macOS ``CALayer`` handle
 and ``NSView`` handle (as void pointers).
 
@@ -194,7 +197,7 @@ and ``NSView`` handle (as void pointers).
 :return: A :class:`WindowingData` corresponding to the given window.
 :rtype: WindowingData
 )");
-inline const WindowingData CreateMacOSWindowingData(void *view, void *layer)
+inline const WindowingData CreateMacOSWindowingData(NSView view, CALayer layer)
 {
   WindowingData ret = {};
 
@@ -224,11 +227,17 @@ outputs.
 )");
   virtual void Shutdown() = 0;
 
-  DOCUMENT("Sets the :class:`TextureDisplay` configuration for a texture output.");
-  virtual void SetTextureDisplay(const TextureDisplay &o) = 0;
+  DOCUMENT(R"(Sets the configuration for a texture output.
 
-  DOCUMENT("Sets the :class:`MeshDisplay` configuration for a mesh output.");
-  virtual void SetMeshDisplay(const MeshDisplay &o) = 0;
+:param TextureDisplay config: The configuration.
+)");
+  virtual void SetTextureDisplay(const TextureDisplay &config) = 0;
+
+  DOCUMENT(R"(Sets the configuration for a mesh output.
+
+:param MeshDisplay config: The configuration.
+)");
+  virtual void SetMeshDisplay(const MeshDisplay &config) = 0;
 
   DOCUMENT(R"(Sets the dimensions of the output, useful only for headless outputs that don't have a
 backing window which don't have any implicit dimensions. This allows configuring a virtual viewport
@@ -245,14 +254,14 @@ which is useful for operations like picking vertices that depends on the output
 the output data is not displayed anywhere natively.
 
 :return: The output texture data as tightly packed RGB 3-byte data.
-:rtype: ``bytes``
+:rtype: bytes
 )");
   virtual bytebuf ReadbackOutputTexture() = 0;
 
   DOCUMENT(R"(Retrieve the current dimensions of the output.
 
 :return: The current width and height of the output.
-:rtype: ``pair`` of two ``int``
+:rtype: Tuple[int,int]
 )");
   virtual rdcpair<int32_t, int32_t> GetDimensions() = 0;
 
@@ -278,7 +287,7 @@ Should only be called for texture outputs.
   texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned
   normalised values.
 :return: A boolean indicating if the thumbnail was successfully created.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool AddThumbnail(WindowingData window, ResourceId textureId, const Subresource &sub,
                             CompType typeCast) = 0;
@@ -298,13 +307,16 @@ Should only be called for texture outputs.
 
 :param WindowingData window: A :class:`WindowingData` describing the native window.
 :return: A boolean indicating if the pixel context was successfully configured.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool SetPixelContext(WindowingData window) = 0;
 
   DOCUMENT(R"(Sets the pixel that the pixel context should be centred on.
 
 Should only be called for texture outputs.
+
+:param int x: The X co-ordinate to highlight.
+:param int y: The Y co-ordinate to highlight.
 )");
   virtual void SetPixelContextLocation(uint32_t x, uint32_t y) = 0;
 
@@ -346,7 +358,7 @@ Should only be called for mesh outputs.
 :param int y: The y co-ordinate to pick from.
 :return: A tuple with the first value being the vertex index in the mesh, and the second value being
   the instance index. The values are set to :data:`NoResult` if no vertex was found, 
-:rtype: ``tuple`` of ``int`` and ``int``
+:rtype: Tuple[int,int]
 )");
   virtual rdcpair<uint32_t, uint32_t> PickVertex(uint32_t x, uint32_t y) = 0;
 
@@ -367,7 +379,7 @@ well as control the replay and analysis functionality available.
   Called whenever some on-going blocking process needs to determine if it should close.
 
   :return: Whether or not the process should be killed.
-  :rtype: ``bool``
+  :rtype: bool
 
 .. function:: ProgressCallback()
 
@@ -409,7 +421,7 @@ struct IReplayController
   DOCUMENT(R"(Retrieves the supported :class:`WindowingSystem` systems by the local system.
 
 :return: The list of supported systems.
-:rtype: ``list`` of :class:`WindowingSystem`
+:rtype: List[WindowingSystem]
 )");
   virtual rdcarray<WindowingSystem> GetSupportedWindowSystems() = 0;
 
@@ -524,7 +536,7 @@ or hardware-specific ISA formats.
 
 :param bool withPipeline: More disassembly may be available when a pipeline is specified.
 :return: The list of disassembly targets available.
-:rtype: ``list`` of ``str``
+:rtype: List[str]
 )");
   virtual rdcarray<rdcstr> GetDisassemblyTargets(bool withPipeline) = 0;
 
@@ -535,7 +547,7 @@ or hardware-specific ISA formats.
 :param str target: The name of the disassembly target to generate for. Must be one of the values
   returned by :meth:`GetDisassemblyTargets`, or empty to use the default generation.
 :return: The disassembly text, or an error message if something went wrong.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr DisassembleShader(ResourceId pipeline, const ShaderReflection *refl,
                                    const rdcstr &target) = 0;
@@ -547,11 +559,11 @@ See :data:`TextureDisplay.customShaderId`.
 :param str entry: The entry point to use when compiling.
 :param ShaderEncoding sourceEncoding: The encoding of the source data.
 :param bytes source: The source data itself.
-:param int compileFlags: API-specific compilation flags.
+:param ShaderCompileFlags compileFlags: API-specific compilation flags.
 :param ShaderStage type: The stage that this shader will be executed at.
 :return: A ``tuple`` with the id of the new shader if compilation was successful,
   :meth:`ResourceId.Null` otherwise, and a ``str`` with any warnings/errors from compilation.
-:rtype: ``tuple`` of :class:`ResourceId` and ``str``.
+:rtype: Tuple[ResourceId,str]
 )");
   virtual rdcpair<ResourceId, rdcstr> BuildCustomShader(const rdcstr &entry,
                                                         ShaderEncoding sourceEncoding, bytebuf source,
@@ -575,11 +587,11 @@ See :meth:`BuildCustomShader`.
 :param ShaderStage type: The stage that this shader will be executed at.
 :return: A ``tuple`` with the id of the new shader if compilation was successful,
   :meth:`ResourceId.Null` otherwise, and a ``str`` with any warnings/errors from compilation.
-:rtype: ``tuple`` of :class:`ResourceId` and ``str``.
+:rtype: Tuple[ResourceId,str]
 )");
   virtual rdcpair<ResourceId, rdcstr> BuildTargetShader(const rdcstr &entry,
                                                         ShaderEncoding sourceEncoding, bytebuf source,
-                                                        const ShaderCompileFlags &flags,
+                                                        const ShaderCompileFlags &compileFlags,
                                                         ShaderStage type) = 0;
 
   DOCUMENT(R"(Retrieve the list of supported :class:`ShaderEncoding` which can be build using
@@ -593,7 +605,7 @@ compiled internally - so compiling externally could be preferable as it allows b
 of the compile process or using alternate/updated tools.
 
 :return: The list of target shader encodings available.
-:rtype: ``list`` of :class:`ShaderEncoding`
+:rtype: List[ShaderEncoding]
 )");
   virtual rdcarray<ShaderEncoding> GetTargetShaderEncodings() = 0;
 
@@ -608,7 +620,7 @@ compiled internally - so compiling externally could be preferable as it allows b
 of the compile process or using alternate/updated tools.
 
 :return: The list of target shader encodings available.
-:rtype: ``list`` of :class:`ShaderEncoding`
+:rtype: List[ShaderEncoding]
 )");
   virtual rdcarray<ShaderEncoding> GetCustomShaderEncodings() = 0;
 
@@ -662,15 +674,15 @@ textures are bound as outputs.
   DOCUMENT(R"(Retrieve the list of root-level drawcalls in the capture.
 
 :return: The list of root-level drawcalls in the capture.
-:rtype: ``list`` of :class:`DrawcallDescription`
+:rtype: List[DrawcallDescription]
 )");
   virtual const rdcarray<DrawcallDescription> &GetDrawcalls() = 0;
 
   DOCUMENT(R"(Retrieve the values of a specified set of counters.
 
-:param list counters: The list of :class:`GPUCounter` to fetch results for.
+:param List[GPUCounter] counters: The list of counters to fetch results for.
 :return: The list of counter results generated.
-:rtype: ``list`` of :class:`CounterResult`
+:rtype: List[CounterResult]
 )");
   virtual rdcarray<CounterResult> FetchCounters(const rdcarray<GPUCounter> &counters) = 0;
 
@@ -678,7 +690,7 @@ textures are bound as outputs.
 implementation.
 
 :return: The list of counters available.
-:rtype: ``list`` of :class:`GPUCounter`
+:rtype: List[GPUCounter]
 )");
   virtual rdcarray<GPUCounter> EnumerateCounters() = 0;
 
@@ -697,21 +709,21 @@ This includes any object allocated a :class:`ResourceId`, that don't have any ot
 are only used as intermediary elements.
 
 :return: The list of resources in the capture.
-:rtype: ``list`` of :class:`ResourceDescription`
+:rtype: List[ResourceDescription]
 )");
   virtual const rdcarray<ResourceDescription> &GetResources() = 0;
 
   DOCUMENT(R"(Retrieve the list of textures alive in the capture.
 
 :return: The list of textures in the capture.
-:rtype: ``list`` of :class:`TextureDescription`
+:rtype: List[TextureDescription]
 )");
   virtual const rdcarray<TextureDescription> &GetTextures() = 0;
 
   DOCUMENT(R"(Retrieve the list of buffers alive in the capture.
 
 :return: The list of buffers in the capture.
-:rtype: ``list`` of :class:`BufferDescription`
+:rtype: List[BufferDescription]
 )");
   virtual const rdcarray<BufferDescription> &GetBuffers() = 0;
 
@@ -721,7 +733,7 @@ Every time this function is called, any debug messages returned will not be retu
 newly generated messages will be returned after that.
 
 :return: The list of the :class:`DebugMessage` messages.
-:rtype: ``list`` of :class:`DebugMessage`
+:rtype: List[DebugMessage]
 )");
   virtual rdcarray<DebugMessage> GetDebugMessages() = 0;
 
@@ -732,7 +744,7 @@ only ever have one result (only one entry point per shader).
 
 :param ResourceId shader: The shader to look up entry points for.
 :return: The list of the :class:`ShaderEntryPoint` messages.
-:rtype: ``list`` of :class:`ShaderEntryPoint`
+:rtype: List[ShaderEntryPoint]
 )");
   virtual rdcarray<ShaderEntryPoint> GetShaderEntryPoints(ResourceId shader) = 0;
 
@@ -779,7 +791,7 @@ only ever have one result (only one entry point per shader).
   texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned
   normalised values.
 :return: A tuple with the minimum and maximum pixel values respectively.
-:rtype: ``tuple`` of PixelValue and PixelValue
+:rtype: Tuple[PixelValue,PixelValue]
 )");
   virtual rdcpair<PixelValue, PixelValue> GetMinMax(ResourceId textureId, const Subresource &sub,
                                                     CompType typeCast) = 0;
@@ -800,10 +812,10 @@ bucket when the pixel values are divided between ``minval`` and ``maxval``.
   not added to any bucket.
 :param float maxval: The upper end of the largest bucket. If any values are above this, they are
   not added to any bucket.
-:param list channels: A list of four ``bool`` values indicating whether each of RGBA should be
-  included in the count.
+:param Tuple[bool,bool,bool,bool] channels: A set of four flags indicating whether each of RGBA
+  respectively should be included in the count.
 :return: A list of the unnormalised bucket values.
-:rtype: ``list`` of ``int``
+:rtype: List[int]
 )");
   virtual rdcarray<uint32_t> GetHistogram(ResourceId textureId, const Subresource &sub,
                                           CompType typeCast, float minval, float maxval,
@@ -821,13 +833,12 @@ bucket when the pixel values are divided between ``minval`` and ``maxval``.
 :param int x: The x co-ordinate.
 :param int y: The y co-ordinate.
 :param Subresource sub: The subresource within this texture to use.
-:param int sampleIdx: The multi-sampled sample. Ignored if non-multisampled texture.
 :param CompType typeCast: If possible interpret the texture with this type instead of its normal
   type. If set to :data:`CompType.Typeless` then no cast is applied, otherwise where allowed the
   texture data will be reinterpreted - e.g. from unsigned integers to floats, or to unsigned
   normalised values.
 :return: The list of pixel history events.
-:rtype: ``list`` of :class:`PixelModification`
+:rtype: List[PixelModification]
 )");
   virtual rdcarray<PixelModification> PixelHistory(ResourceId texture, uint32_t x, uint32_t y,
                                                    const Subresource &sub, CompType typeCast) = 0;
@@ -868,8 +879,8 @@ bucket when the pixel values are divided between ``minval`` and ``maxval``.
 
   DOCUMENT(R"(Retrieve a debugging trace from running a compute thread.
 
-:param groupid: A list containing the 3D workgroup index.
-:param threadid: A list containing the 3D thread index within the above workgroup.
+:param Tuple[int,int,int] groupid: A list containing the 3D workgroup index.
+:param Tuple[int,int,int] threadid: A list containing the 3D thread index within the workgroup.
 :return: The resulting trace resulting from debugging. Destroy with
   :meth:`FreeTrace`.
 :rtype: ShaderDebugTrace
@@ -886,7 +897,7 @@ completed, further calls will return an empty list.
 
 :param ShaderDebugger debugger: The shader debugger to continue running.
 :return: A number of subsequent states.
-:rtype: ``list`` of :class:`ShaderDebugTrace`
+:rtype: List[ShaderDebugState]
 )");
   virtual rdcarray<ShaderDebugState> ContinueDebug(ShaderDebugger *debugger) = 0;
 
@@ -900,7 +911,7 @@ completed, further calls will return an empty list.
 
 :param ResourceId id: The id of the texture or buffer resource to be queried.
 :return: The list of usages of the resource.
-:rtype: ``list`` of :class:`EventUsage`
+:rtype: List[EventUsage]
 )");
   virtual rdcarray<EventUsage> GetUsage(ResourceId id) = 0;
 
@@ -917,7 +928,7 @@ otherwise.
 :param int length: Retrieve this many bytes after :paramref:`offset`. May be 0 to fetch the rest of the
   buffer.
 :return: The shader variables with their contents.
-:rtype: ``list`` of :class:`ShaderVariable`
+:rtype: List[ShaderVariable]
 )");
   virtual rdcarray<ShaderVariable> GetCBufferVariableContents(ResourceId pipeline, ResourceId shader,
                                                               const rdcstr &entryPoint,
@@ -930,7 +941,7 @@ texture to something compatible with the target file format.
 :param TextureSave saveData: The configuration settings of which texture to save, and how
 :param str path: The path to save to on disk.
 :return: ``True`` if the texture was saved successfully, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool SaveTexture(const TextureSave &saveData, const rdcstr &path) = 0;
 
@@ -950,7 +961,7 @@ texture to something compatible with the target file format.
 :param int offset: The byte offset to the start of the range.
 :param int len: The length of the range, or 0 to retrieve the rest of the bytes in the buffer.
 :return: The requested buffer contents.
-:rtype: ``bytes``
+:rtype: bytes
 )");
   virtual bytebuf GetBufferData(ResourceId buff, uint64_t offset, uint64_t len) = 0;
 
@@ -959,7 +970,7 @@ texture to something compatible with the target file format.
 :param ResourceId tex: The id of the texture to retrieve data from.
 :param Subresource sub: The subresource within this texture to use.
 :return: The requested texture contents.
-:rtype: ``bytes``
+:rtype: bytes
 )");
   virtual bytebuf GetTextureData(ResourceId tex, const Subresource &sub) = 0;
 
@@ -983,35 +994,35 @@ struct ITargetControl
   DOCUMENT(R"(Determines if the connection is still alive.
 
 :return: ``True`` if the connection still appears to be working, ``False`` if it has been closed.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool Connected() = 0;
 
   DOCUMENT(R"(Retrieves the target's name or identifier - typically the name of the executable.
 
 :return: The target name.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr GetTarget() = 0;
 
   DOCUMENT(R"(Retrieves the API currently in use by the target.
 
 :return: The API name, or empty if no API is initialised yet.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr GetAPI() = 0;
 
   DOCUMENT(R"(Retrieves the Process ID (PID) of the target on its local system.
 
 :return: The Process ID, or 0 if that's not applicable on the target platform.
-:rtype: ``int``
+:rtype: int
 )");
   virtual uint32_t GetPID() = 0;
 
   DOCUMENT(R"(If a busy message was received, determine the client keeping the target busy.
 
 :return: The name of the client currently connected to the target.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr GetBusyClient() = 0;
 
@@ -1087,16 +1098,16 @@ struct ICaptureAccess
 :class:`ReplayOptions` to force replay on a particular GPU.
 
 :return: The list of GPUs available.
-:rtype: ``list`` of :class:`GPUDevice`
+:rtype: List[GPUDevice]
 )");
   virtual rdcarray<GPUDevice> GetAvailableGPUs() = 0;
 
   DOCUMENT(R"(Retrieve the total number of available sections.
 
 :return: The number of sections in the capture
-:rtype: ``int``.
+:rtype: int
 )");
-  virtual int GetSectionCount() = 0;
+  virtual int32_t GetSectionCount() = 0;
 
   DOCUMENT(R"(Locate the index of a section by its name. Returns ``-1`` if the section is not found.
 
@@ -1104,9 +1115,9 @@ This index should not be cached, as writing sections could re-order the indices.
 
 :param str name: The name of the section to search for.
 :return: The index of the section, or ``-1`` if not found.
-:rtype: ``int``.
+:rtype: int
 )");
-  virtual int FindSectionByName(const rdcstr &name) = 0;
+  virtual int32_t FindSectionByName(const rdcstr &name) = 0;
 
   DOCUMENT(R"(Locate the index of a section by its type. Returns ``-1`` if the section is not found.
 
@@ -1114,9 +1125,9 @@ This index should not be cached, as writing sections could re-order the indices.
 
 :param SectionType type: The type of the section to search for.
 :return: The index of the section, or ``-1`` if not found.
-:rtype: ``int``.
+:rtype: int
 )");
-  virtual int FindSectionByType(SectionType type) = 0;
+  virtual int32_t FindSectionByType(SectionType type) = 0;
 
   DOCUMENT(R"(Get the describing properties of the specified section.
 
@@ -1124,15 +1135,15 @@ This index should not be cached, as writing sections could re-order the indices.
 :return: The properties of the section, if the index is valid.
 :rtype: SectionProperties
 )");
-  virtual SectionProperties GetSectionProperties(int index) = 0;
+  virtual SectionProperties GetSectionProperties(int32_t index) = 0;
 
   DOCUMENT(R"(Get the raw byte contents of the specified section.
 
 :param int index: The index of the section.
 :return: The raw contents of the section, if the index is valid.
-:rtype: ``bytes``.
+:rtype: bytes
 )");
-  virtual bytebuf GetSectionContents(int index) = 0;
+  virtual bytebuf GetSectionContents(int32_t index) = 0;
 
   DOCUMENT(R"(Writes a new section with specified properties and contents. If an existing section
 already has the same type or name, it will be overwritten (two sections cannot share the same type
@@ -1141,14 +1152,14 @@ or name).
 :param SectionProperties props: The properties of the section to be written.
 :param bytes contents: The raw contents of the section.
 :return: ``True`` if the section was written successfully, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool WriteSection(const SectionProperties &props, const bytebuf &contents) = 0;
 
   DOCUMENT(R"(Query if callstacks are available.
 
 :return: ``True`` if any callstacks are available, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool HasCallstacks() = 0;
 
@@ -1165,7 +1176,7 @@ separate thread.
 :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.
 :return: ``True`` if the resolver successfully initialised, ``False`` if something went wrong.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool InitResolver(bool interactive, RENDERDOC_ProgressCallback progress) = 0;
 
@@ -1173,16 +1184,16 @@ separate thread.
 
 Must only be called after :meth:`InitResolver` has returned ``True``.
 
-:param list callstack: The integer addresses in the original callstack.
+:param List[int] callstack: The integer addresses in the original callstack.
 :return: The list of resolved callstack entries as strings.
-:rtype: ``list`` of ``str``
+:rtype: List[str]
 )");
   virtual rdcarray<rdcstr> GetResolve(const rdcarray<uint64_t> &callstack) = 0;
 
   DOCUMENT(R"(Retrieves the name of the driver that was used to create this capture.
 
 :return: A simple string identifying the driver used to make the capture.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr DriverName() = 0;
 
@@ -1212,7 +1223,7 @@ struct IRemoteServer : public ICaptureAccess
 
 :return: ``True`` if the ping was sent and received successfully, ``False`` if something went wrong
   and the connection is no longer alive.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool Ping() = 0;
 
@@ -1221,7 +1232,7 @@ struct IRemoteServer : public ICaptureAccess
 These will be strings like "D3D11" or "OpenGL".
 
 :return: A list of names of the local proxies.
-:rtype: ``list`` of ``str``
+:rtype: List[str]
 )");
   virtual rdcarray<rdcstr> LocalProxies() = 0;
 
@@ -1230,14 +1241,14 @@ These will be strings like "D3D11" or "OpenGL".
 These will be strings like "D3D11" or "OpenGL".
 
 :return: A list of names of the remote renderers.
-:rtype: ``list`` of ``str``
+:rtype: List[str]
 )");
   virtual rdcarray<rdcstr> RemoteSupportedReplays() = 0;
 
   DOCUMENT(R"(Retrieve the path on the remote system where browsing can begin.
 
 :return: The 'home' path where browsing for files or folders can begin.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr GetHomeFolder() = 0;
 
@@ -1247,7 +1258,7 @@ If an error occurs, a single :class:`PathEntry` will be returned with appropriat
 
 :param str path: The remote path to list.
 :return: The contents of the specified folder.
-:rtype: ``list`` of :class:`PathEntry`
+:rtype: List[PathEntry]
 )");
   virtual rdcarray<PathEntry> ListFolder(const rdcstr &path) = 0;
 
@@ -1260,7 +1271,8 @@ This happens on the remote system, so all paths are relative to the remote files
   directory containing the application is used.
 :param str cmdLine: The command line to use when running the application, it will be processed in a
   platform specific way to generate arguments.
-:param list env: Any :class:`EnvironmentModification` that should be made when running the program.
+:param List[EnvironmentModification] env: Any environment changes that should be made when running
+  the program.
 :param CaptureOptions opts: The capture options to use when injecting into the program.
 :return: The :class:`ExecuteResult` indicating both the status of the operation (success or failure)
   and any reason for failure, or else the ident where the new application is listening for target
@@ -1296,7 +1308,7 @@ the capture must be available on the machine where the replay happens.
 :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.
 :return: The path on the remote system where the capture was saved temporarily.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr CopyCaptureToRemote(const rdcstr &filename, RENDERDOC_ProgressCallback progress) = 0;
 
@@ -1332,7 +1344,7 @@ or an error has occurred.
   value for the opening. Can be ``None`` if no progress is desired.
 :return: A tuple containing the status of opening the capture, whether success or failure, and the
   resulting :class:`ReplayController` handle if successful.
-:rtype: ``tuple`` of :class:`ReplayStatus` and :class:`ReplayController`
+:rtype: Tuple[ReplayStatus,ReplayController]
 )");
   virtual rdcpair<ReplayStatus, IReplayController *> OpenCapture(
       uint32_t proxyid, const rdcstr &logfile, const ReplayOptions &opts,
@@ -1404,7 +1416,7 @@ file.
 
 :param str filename: The filename to copy to.
 :return: ``True`` if the operation succeeded.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool CopyFileTo(const rdcstr &filename) = 0;
 
@@ -1433,14 +1445,14 @@ The error string is not reset by calling this function so it's safe to call mult
 any other function call may reset the error string to empty.
 
 :return: The error string, if one exists, or an empty string.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr ErrorString() = 0;
 
   DOCUMENT(R"(Returns the list of capture file formats.
 
 :return: The list of capture file formats available.
-:rtype: ``list`` of :class:`CaptureFileFormat`
+:rtype: List[CaptureFileFormat]
 )");
   virtual rdcarray<CaptureFileFormat> GetCaptureFileFormats() = 0;
 
@@ -1457,7 +1469,7 @@ replay support.
   DOCUMENT(R"(Retrieves the identifying string describing what type of machine created this capture.
 
 :return: A string identifying the machine ident used to make the capture.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr RecordedMachineIdent() = 0;
 
@@ -1465,7 +1477,7 @@ replay support.
 be 0 if all timestamps are already absolute.
 
 :return: The timestamp base value
-:rtype: ``int``
+:rtype: int
 )");
   virtual uint64_t TimestampBase() = 0;
 
@@ -1473,7 +1485,7 @@ be 0 if all timestamps are already absolute.
 microseconds. May be 1.0 if all timestamps and durations are already in microseconds.
 
 :return: The timestamp frequency
-:rtype: ``float``
+:rtype: float
 )");
   virtual double TimestampFrequency() = 0;
 
@@ -1520,7 +1532,7 @@ by the :class:`ReplayController`.
   value for the opening. Can be ``None`` if no progress is desired.
 :return: A tuple containing the status of opening the capture, whether success or failure, and the
   resulting :class:`ReplayController` handle if successful.
-:rtype: ``tuple`` of :class:`ReplayStatus` and :class:`ReplayController`.
+:rtype: Tuple[ReplayStatus,ReplayController]
 )");
   virtual rdcpair<ReplayStatus, IReplayController *> OpenCapture(
       const ReplayOptions &opts, RENDERDOC_ProgressCallback progress) = 0;
@@ -1670,16 +1682,16 @@ float.
 
 :param int half: The half stored as an int.
 :return: The floating point equivalent.
-:rtype: ``float``
+:rtype: float
 )");
 extern "C" RENDERDOC_API float RENDERDOC_CC RENDERDOC_HalfToFloat(uint16_t half);
 
 DOCUMENT(R"(A utility function that converts a float to a half (stored in a 16-bit unsigned
 integer).
 
-:param float f: The floating point value.
+:param float flt: The floating point value.
 :return: The nearest half-float equivalent stored as an int.
-:rtype: ``int``
+:rtype: int
 )");
 extern "C" RENDERDOC_API uint16_t RENDERDOC_CC RENDERDOC_FloatToHalf(float flt);
 
@@ -1690,7 +1702,7 @@ topology.
 
 :param Topology topology: The topology to query about.
 :return: The number of vertices in a single primitive.
-:rtype: ``int``
+:rtype: int
 )");
 extern "C" RENDERDOC_API uint32_t RENDERDOC_CC RENDERDOC_NumVerticesPerPrimitive(Topology topology);
 
@@ -1701,7 +1713,7 @@ case of strip topologies.
 :param Topology topology: The topology to query about.
 :param int primitive: The primitive to query about.
 :return: The vertex offset where the primitive starts.
-:rtype: ``int``
+:rtype: int
 )");
 extern "C" RENDERDOC_API uint32_t RENDERDOC_CC RENDERDOC_VertexOffset(Topology topology,
                                                                       uint32_t primitive);
@@ -1754,7 +1766,7 @@ This function will block for a variable timeout depending on how many targets ar
   specified then default TCP enumeration happens.
 :param int nextIdent: The next ident to scan.
 :return: The ident of the next active target, or ``0`` if no other targets exist.
-:rtype: ``int``
+:rtype: int
 )");
 extern "C" RENDERDOC_API uint32_t RENDERDOC_CC RENDERDOC_EnumerateRemoteTargets(const rdcstr &URL,
                                                                                 uint32_t nextIdent);
@@ -1769,7 +1781,7 @@ DOCUMENT(R"(Create a connection to a remote server running on given hostname.
   specified then default TCP enumeration happens.
 :return: The status of opening the connection, whether success or failure, and a :class:`RemoteServer`
   instance if it were successful
-:rtype: ``pair`` of ReplayStatus and RemoteServer
+:rtype: Tuple[ReplayStatus,RemoteServer]
 )");
 extern "C" RENDERDOC_API ReplayStatus RENDERDOC_CC
 RENDERDOC_CreateRemoteServerConnection(const rdcstr &URL, IRemoteServer **rend);
@@ -1793,7 +1805,7 @@ from external sources.
 This function will block until a remote connection tells the server to shut down, or the
 ``killReplay`` callback returns ``True``.
 
-:param str host: The name of the interface to listen on.
+:param str listenhost: The name of the interface to listen on.
 :param KillCallback killReplay: A callback that returns a ``bool`` indicating if the server should
   be shut down or not.
 :param PreviewWindowCallback previewWindow: A callback that returns information for a preview window
@@ -1830,7 +1842,7 @@ This function must be called when the process is running with administrator/supe
 :param CaptureOptions opts: The capture options to use when injecting into the program.
 :return: ``True`` if the hook is active, ``False`` if something went wrong. The hook must be closed
   with :func:`StopGlobalHook` before the application is closed.
-:rtype: ``bool``
+:rtype: bool
 )");
 extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_StartGlobalHook(const rdcstr &pathmatch,
                                                                      const rdcstr &logfile,
@@ -1848,14 +1860,14 @@ DOCUMENT(R"(Determines if the global hook is active or not.
 This function can only be called if global hooking is supported (see :func:`CanGlobalHook`).
 
 :return: ``True`` if the hook is active, or ``False`` if the hook is inactive.
-:rtype: ``bool``
+:rtype: bool
 )");
 extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_IsGlobalHookActive();
 
 DOCUMENT(R"(Determines if the global hook is supported on the current platform and configuration.
 
 :return: ``True`` if global hooking can be used on the platform, ``False`` if not.
-:rtype: ``bool``
+:rtype: bool
 )");
 extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_CanGlobalHook();
 
@@ -1866,7 +1878,8 @@ DOCUMENT(R"(Launch an application and inject into it to allow capturing.
   directory containing the application is used.
 :param str cmdLine: The command line to use when running the application, it will be processed in a
   platform specific way to generate arguments.
-:param list env: Any :class:`EnvironmentModification` that should be made when running the program.
+:param List[EnvironmentModification] env: Any environment changes that should be made when running
+  the program.
 :param str capturefile: The capture file path template, or blank to use a default location.
 :param CaptureOptions opts: The capture options to use when injecting into the program.
 :param bool waitForExit: If ``True`` this function will block until the process exits.
@@ -1883,7 +1896,8 @@ RENDERDOC_ExecuteAndInject(const rdcstr &app, const rdcstr &workingDir, const rd
 DOCUMENT(R"(Where supported by operating system and permissions, inject into a running process.
 
 :param int pid: The Process ID (PID) to inject into.
-:param list env: Any :class:`EnvironmentModification` that should be made when running the program.
+:param List[EnvironmentModification] env: Any environment changes that should be made when running
+  the program.
 :param str capturefile: The capture file path template, or blank to use a default location.
 :param CaptureOptions opts: The capture options to use when injecting into the program.
 :param bool waitForExit: If ``True`` this function will block until the process exits.
@@ -1948,9 +1962,9 @@ has been called. It should be called exactly once, and before shutdown you must
 :func:`ShutdownReplay`.
 
 :param GlobalEnvironment globalEnv: The path to the new log file.
-:param ``list`` of ``str`` args: Any extra command-line arguments.
+:param List[str] args: Any extra command-line arguments.
 )");
-extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_InitialiseReplay(GlobalEnvironment env,
+extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_InitialiseReplay(GlobalEnvironment globalEnv,
                                                                       const rdcarray<rdcstr> &args);
 
 DOCUMENT(R"(Shutdown RenderDoc for replay. Replay API functions should not be called after this
@@ -1984,7 +1998,7 @@ DOCUMENT(R"(Gets the location for the diagnostic log output, shared by captured
 analysis program.
 
 :return: The path to the current log file.
-:rtype: ``str``
+:rtype: str
 )");
 extern "C" RENDERDOC_API const char *RENDERDOC_CC RENDERDOC_GetLogFile();
 
@@ -2004,7 +2018,7 @@ DOCUMENT(R"(Add a message to RenderDoc's logfile.
 :param str text: The text of the message.
 )");
 extern "C" RENDERDOC_API void RENDERDOC_CC RENDERDOC_LogMessage(LogType type, const rdcstr &project,
-                                                                const rdcstr &file, unsigned int line,
+                                                                const rdcstr &file, uint32_t line,
                                                                 const rdcstr &text);
 
 DOCUMENT(R"(Retrieves the version string.
@@ -2012,14 +2026,14 @@ DOCUMENT(R"(Retrieves the version string.
 This will be in the form "MAJOR.MINOR"
 
 :return: The version string.
-:rtype: ``str``
+:rtype: str
 )");
 extern "C" RENDERDOC_API const char *RENDERDOC_CC RENDERDOC_GetVersionString();
 
 DOCUMENT(R"(Determines if this is a release build of RenderDoc or not.
 
 :return: ``True`` if the replay is running on a release build.
-:rtype: ``bool``
+:rtype: bool
 )");
 extern "C" RENDERDOC_API bool RENDERDOC_CC RENDERDOC_IsReleaseBuild();
 
@@ -2028,7 +2042,7 @@ DOCUMENT(R"(Retrieves the commit hash used to build.
 This will be in the form "0123456789abcdef0123456789abcdef01234567"
 
 :return: The commit hash.
-:rtype: ``str``
+:rtype: str
 )");
 extern "C" RENDERDOC_API const char *RENDERDOC_CC RENDERDOC_GetCommitHash();
 
@@ -2043,7 +2057,7 @@ extern "C" RENDERDOC_API DriverInformation RENDERDOC_CC RENDERDOC_GetDriverInfor
 DOCUMENT(R"(Returns the current process's memory usage in bytes
 
 :return: The current memory usage in bytes.
-:rtype: ``int``
+:rtype: int
 )");
 extern "C" RENDERDOC_API uint64_t RENDERDOC_CC RENDERDOC_GetCurrentProcessMemoryUsage();
 
@@ -2056,8 +2070,9 @@ the setting's value, description, etc.
 
 If no such setting exists, `None` is returned.
 
+:param str name: The name of the setting.
 :return: The specified setting.
-:rtype: ``SDObject``
+:rtype: SDObject
 )");
 extern "C" RENDERDOC_API const SDObject *RENDERDOC_CC RENDERDOC_GetConfigSetting(const rdcstr &name);
 
@@ -2066,8 +2081,9 @@ value object.
 
 If no such setting exists, `None` is returned.
 
+:param str name: The name of the setting.
 :return: The specified setting.
-:rtype: ``SDObject``
+:rtype: SDObject
 )");
 extern "C" RENDERDOC_API SDObject *RENDERDOC_CC RENDERDOC_SetConfigSetting(const rdcstr &name);
 
@@ -2104,7 +2120,7 @@ struct IDeviceProtocolController
   DOCUMENT(R"(Retrieves the name of this protocol as passed to :func:`GetDeviceProtocolController`.
 
 :return: A string identifying the protocol.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr GetProtocolName() = 0;
 
@@ -2118,7 +2134,7 @@ The returned string is the hostname of the device, which can be connected via
 ``protocol://hostname`` with interfaces that take a hostname.
 
 :return: A list of the devices currently available.
-:rtype: ``list`` of ``str``
+:rtype: List[str]
 )");
   virtual rdcarray<rdcstr> GetDevices() = 0;
 
@@ -2128,7 +2144,7 @@ correlate to a device than the hostname which may be only a programmatic identif
 :param str URL: The URL of the device in the form ``protocol://host``, with protocol as returned by
   :func:`GetProtocolName` and host as returned by :func:`GetDevices`.
 :return: A string identifying the device.
-:rtype: ``str``
+:rtype: str
 )");
   virtual rdcstr GetFriendlyName(const rdcstr &URL) = 0;
 
@@ -2138,7 +2154,7 @@ user can be prompted to close an existing program before a new one is launched.
 :param str URL: The URL of the device in the form ``protocol://host``, with protocol as returned by
   :func:`GetProtocolName` and host as returned by :func:`GetDevices`.
 :return: ``True`` if the device supports multiple programs, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool SupportsMultiplePrograms(const rdcstr &URL) = 0;
 
@@ -2147,7 +2163,7 @@ user can be prompted to close an existing program before a new one is launched.
 :param str URL: The URL of the device in the form ``protocol://host``, with protocol as returned by
   :func:`GetProtocolName` and host as returned by :func:`GetDevices`.
 :return: ``True`` if any the device is supported, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   virtual bool IsSupported(const rdcstr &URL) = 0;
 
@@ -2168,7 +2184,7 @@ protected:
 DOCUMENT(R"(Retrieve the set of device protocols supported (see :func:`GetDeviceProtocolController`).
 
 :return: The supported device protocols.
-:rtype: ``list`` of ``str``
+:rtype: List[str]
 )");
 extern "C" RENDERDOC_API void RENDERDOC_CC
 RENDERDOC_GetSupportedDeviceProtocols(rdcarray<rdcstr> *supportedProtocols);

renderdoc/api/replay/replay_enums.h

@@ -1735,6 +1735,7 @@ DOCUMENT(R"(Check if an API is D3D or not
 
 :param GraphicsAPI api: The graphics API in question
 :return: ``True`` if api is a D3D-based API, ``False`` otherwise
+:rtype: bool
 )");
 constexpr inline bool IsD3D(GraphicsAPI api)
 {
@@ -1785,9 +1786,9 @@ DECLARE_REFLECTION_ENUM(ShaderEncoding);
 
 DOCUMENT(R"(Check whether or not this is a human readable text representation.
 
-:param ShaderEncoding e: The encoding to check.
+:param ShaderEncoding encoding: The encoding to check.
 :return: ``True`` if it describes a text representation, ``False`` for a bytecode representation.
-:rtype: ``bool``
+:rtype: bool
 )");
 constexpr inline bool IsTextRepresentation(ShaderEncoding encoding)
 {
@@ -2047,9 +2048,9 @@ DOCUMENT(R"(Return the number of control points in a patch list ``Topology``
 
 ``t`` must be a patch list topology, the return value will be between 1 and 32 inclusive
 
-:param Topology t: The patch list topology
+:param Topology topology: The patch list topology
 :return: The number of control points in the specified topology
-:rtype: ``int``
+:rtype: int
 )");
 constexpr inline uint32_t PatchList_Count(Topology topology)
 {
@@ -2063,9 +2064,9 @@ DOCUMENT(R"(Check whether or not this topology supports primitive restart.
 .. note:: This is almost but not quite the same as being a line/triangle strip - triangle fans
   also support restart. See also :func:`IsStrip`.
 
-:param Topology t: The topology to check.
+:param Topology topology: The topology to check.
 :return: ``True`` if it describes a topology that allows restart, ``False`` for a list.
-:rtype: ``bool``
+:rtype: bool
 )");
 constexpr inline bool SupportsRestart(Topology topology)
 {
@@ -2076,9 +2077,9 @@ constexpr inline bool SupportsRestart(Topology topology)
 
 DOCUMENT(R"(Check whether or not this is a strip-type topology.
 
-:param Topology t: The topology to check.
+:param Topology topology: The topology to check.
 :return: ``True`` if it describes a strip topology, ``False`` for a list.
-:rtype: ``bool``
+:rtype: bool
 )");
 constexpr inline bool IsStrip(Topology topology)
 {
@@ -3297,7 +3298,7 @@ DOCUMENT(R"(Check whether or not this is a Generic counter.
 
 :param GPUCounter c: The counter.
 :return: ``True`` if it is a generic counter, ``False`` if it's not.
-:rtype: ``bool``
+:rtype: bool
 )");
 inline constexpr bool IsGenericCounter(GPUCounter c)
 {
@@ -3308,7 +3309,7 @@ DOCUMENT(R"(Check whether or not this is an AMD private counter.
 
 :param GPUCounter c: The counter.
 :return: ``True`` if it is an AMD private counter, ``False`` if it's not.
-:rtype: ``bool``
+:rtype: bool
 )");
 inline constexpr bool IsAMDCounter(GPUCounter c)
 {
@@ -3319,7 +3320,7 @@ DOCUMENT(R"(Check whether or not this is an Intel private counter.
 
 :param GPUCounter c: The counter.
 :return: ``True`` if it is an Intel private counter, ``False`` if it's not.
-:rtype: ``bool``
+:rtype: bool
 )");
 inline constexpr bool IsIntelCounter(GPUCounter c)
 {
@@ -3330,7 +3331,7 @@ DOCUMENT(R"(Check whether or not this is an Nvidia private counter.
 
 :param GPUCounter c: The counter.
 :return: ``True`` if it is an Nvidia private counter, ``False`` if it's not.
-:rtype: ``bool``
+:rtype: bool
 )");
 inline constexpr bool IsNvidiaCounter(GPUCounter c)
 {
@@ -3341,7 +3342,7 @@ DOCUMENT(R"(Check whether or not this is a KHR counter.
 
 :param GPUCounter c: The counter.
 :return: ``True`` if it is a Vulkan counter reported through the VK_KHR_performance_query extension, ``False`` if it's not.
-:rtype: ``bool``
+:rtype: bool
 )");
 inline constexpr bool IsVulkanExtendedCounter(GPUCounter c)
 {
@@ -3352,7 +3353,7 @@ DOCUMENT(R"(Check whether or not this is an ARM private counter.
 
 :param GPUCounter c: The counter.
 :return: ``True`` if it is an ARM private counter, ``False`` if it's not.
-:rtype: ``bool``
+:rtype: bool
 )");
 inline constexpr bool IsARMCounter(GPUCounter c)
 {

renderdoc/api/replay/shader_types.h

@@ -560,9 +560,10 @@ struct LineColumnInfo
     return false;
   }
 
-  DOCUMENT(R"(:return: ``True`` if this object is equal to the parameter, disregarding
-  :data:`disassemblyLine`.
-:rtype: ``bool``
+  DOCUMENT(R"(
+:param LineColumnInfo o: The object to compare against.
+:return: ``True`` if this object is equal to the parameter, disregarding :data:`disassemblyLine`.
+:rtype: bool
 )");
   bool SourceEqual(const LineColumnInfo &o) const
   {
@@ -691,9 +692,11 @@ a different debug variable.
 )");
   rdcarray<SourceVariableMapping> sourceVars;
 
-  DOCUMENT(R"(A ``list`` of ``str`` with each function call in the current callstack at this line.
+  DOCUMENT(R"(The function names in the current callstack at this line.
 
 The oldest/outer function is first in the list, the newest/inner function is last.
+
+:type: List[str]
 )");
   rdcarray<rdcstr> callstack;
 };
@@ -781,8 +784,10 @@ If this is ``None`` then the trace is invalid.
 )");
   ShaderDebugger *debugger = NULL;
 
-  DOCUMENT(R"(A ``list`` of :class:`LineColumnInfo` detailing which source lines each instruction
-corresponds to
+  DOCUMENT(R"(An array of the same size as the number of instructions in the shader, with a mapping
+to source lines.
+
+:type: List[LineColumnInfo]
 )");
   rdcarray<LineColumnInfo> lineInfo;
 };

renderdoc/api/replay/structured_data.h

@@ -314,7 +314,7 @@ private:
 
 DECLARE_REFLECTION_STRUCT(SDObjectPODData);
 
-DOCUMENT("A ``list`` of :class:`SDObject` objects");
+DOCUMENT("INTERNAL: An array of SDObject*, mapped to a pure list in python");
 struct StructuredObjectList : public rdcarray<SDObject *>
 {
   StructuredObjectList() : rdcarray<SDObject *>() {}
@@ -500,7 +500,10 @@ struct SDObject
     m_Parent = NULL;
   }
 
-  DOCUMENT("Create a deep copy of this object.");
+  DOCUMENT(R"(
+:return: A new deep copy of this object, which the caller owns.
+:rtype: SDObject
+)");
   SDObject *Duplicate() const
   {
     SDObject *ret = new SDObject();
@@ -535,30 +538,30 @@ recursively through children.
 
 :param SDObject obj: The object to compare against
 :return: A boolean indicating if the object is equal to this one.
-:rtype: ``bool``
+:rtype: bool
 )");
-  bool HasEqualValue(const SDObject *o) const
+  bool HasEqualValue(const SDObject *obj) const
   {
     bool ret = true;
 
-    if(data.str != o->data.str)
+    if(data.str != obj->data.str)
     {
       ret = false;
     }
-    else if(data.basic.u != o->data.basic.u)
+    else if(data.basic.u != obj->data.basic.u)
     {
       ret = false;
     }
-    else if(data.children.size() != o->data.children.size())
+    else if(data.children.size() != obj->data.children.size())
     {
       ret = false;
     }
     else
     {
-      for(size_t c = 0; c < o->data.children.size(); c++)
+      for(size_t c = 0; c < obj->data.children.size(); c++)
       {
         PopulateChild(c);
-        ret &= data.children[c]->HasEqualValue(o->GetChild(c));
+        ret &= data.children[c]->HasEqualValue(obj->GetChild(c));
       }
     }
 
@@ -569,7 +572,7 @@ recursively through children.
   // python.
   DOCUMENT(R"(Add a new child object.
 
-:param SDObject obj: The new child to add
+:param SDObject child: The new child to add
 )");
   inline void DuplicateAndAddChild(const SDObject *child)
   {
@@ -583,7 +586,7 @@ recursively through children.
   DOCUMENT(R"(Find a child object by a given name. If no matching child is found, ``None`` is
 returned.
 
-:param str name: The name to search for.
+:param str childName: The name to search for.
 :return: A reference to the child object if found, or ``None`` if not.
 :rtype: SDObject
 )");
@@ -670,7 +673,7 @@ returned.
   DOCUMENT(R"(Get the number of child objects.
 
 :return: The number of children this object contains.
-:rtype: ``int``
+:rtype: int
 )");
   inline size_t NumChildren() const { return data.children.size(); }
 #if !defined(SWIG)
@@ -821,11 +824,17 @@ returned.
   // these are common to both python and C++
   DOCUMENT(R"(Interprets the object as a ``bool`` and returns its value.
 Invalid if the object is not actually a ``bool``.
+
+:return: The interpreted bool value.
+:rtype: bool
 )");
   inline bool AsBool() const { return data.basic.b; }
   // these are common to both python and C++
   DOCUMENT(R"(Interprets the object as a :class:`ResourceId` and returns its value.
 Invalid if the object is not actually a :class:`ResourceId`.
+
+:return: The interpreted ID.
+:rtype: ResourceId
 )");
   inline ResourceId AsResourceId() const { return data.basic.id; }
 #if defined(RENDERDOC_QT_COMPAT)
@@ -1047,7 +1056,17 @@ inline SDObject *makeSDObject(const rdcinflexiblestr &name, QVariant val)
 }
 #endif
 
-DOCUMENT("Make a structured object out of a signed integer");
+DOCUMENT(R"(Make a structured object as a signed 64-bit integer.
+
+.. note::
+  You should ensure that the value you pass in has already been truncated to the appropriate range
+  for the storage, as the resulting object will be undefined if the value is out of the valid range.
+
+:param str name: The name of the object.
+:param int val: The integer which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDInt64(const rdcinflexiblestr &name, int64_t val)
 {
   SDObject *ret = new SDObject(name, "int64_t"_lit);
@@ -1057,7 +1076,17 @@ inline SDObject *makeSDInt64(const rdcinflexiblestr &name, int64_t val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of an unsigned integer");
+DOCUMENT(R"(Make a structured object as an unsigned 64-bit integer.
+
+.. note::
+  You should ensure that the value you pass in has already been truncated to the appropriate range
+  for the storage, as the resulting object will be undefined if the value is out of the valid range.
+
+:param str name: The name of the object.
+:param int val: The integer which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDUInt64(const rdcinflexiblestr &name, uint64_t val)
 {
   SDObject *ret = new SDObject(name, "uint64_t"_lit);
@@ -1067,7 +1096,17 @@ inline SDObject *makeSDUInt64(const rdcinflexiblestr &name, uint64_t val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of a integer, stored as signed 32-bits");
+DOCUMENT(R"(Make a structured object as a signed 32-bit integer.
+
+.. note::
+  You should ensure that the value you pass in has already been truncated to the appropriate range
+  for the storage, as the resulting object will be undefined if the value is out of the valid range.
+
+:param str name: The name of the object.
+:param int val: The integer which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDInt32(const rdcinflexiblestr &name, int32_t val)
 {
   SDObject *ret = new SDObject(name, "int32_t"_lit);
@@ -1077,7 +1116,17 @@ inline SDObject *makeSDInt32(const rdcinflexiblestr &name, int32_t val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of a integer, stored as unsigned 32-bits");
+DOCUMENT(R"(Make a structured object as an unsigned 32-bit integer.
+
+.. note::
+  You should ensure that the value you pass in has already been truncated to the appropriate range
+  for the storage, as the resulting object will be undefined if the value is out of the valid range.
+
+:param str name: The name of the object.
+:param int val: The integer which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDUInt32(const rdcinflexiblestr &name, uint32_t val)
 {
   SDObject *ret = new SDObject(name, "uint32_t"_lit);
@@ -1087,7 +1136,17 @@ inline SDObject *makeSDUInt32(const rdcinflexiblestr &name, uint32_t val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of a floating point value");
+DOCUMENT(R"(Make a structured object as a 32-bit float.
+
+.. note::
+  You should ensure that the value you pass in has already been truncated to the appropriate range
+  for the storage, as the resulting object will be undefined if the value is out of the valid range.
+
+:param str name: The name of the object.
+:param float val: The float which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDFloat(const rdcinflexiblestr &name, float val)
 {
   SDObject *ret = new SDObject(name, "float"_lit);
@@ -1097,7 +1156,13 @@ inline SDObject *makeSDFloat(const rdcinflexiblestr &name, float val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of a boolean value");
+DOCUMENT(R"(Make a structured object as a boolean value.
+
+:param str name: The name of the object.
+:param bool val: The bool which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDBool(const rdcinflexiblestr &name, bool val)
 {
   SDObject *ret = new SDObject(name, "bool"_lit);
@@ -1107,7 +1172,13 @@ inline SDObject *makeSDBool(const rdcinflexiblestr &name, bool val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of a string");
+DOCUMENT(R"(Make a structured object as a string value.
+
+:param str name: The name of the object.
+:param str val: The string which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDString(const rdcinflexiblestr &name, const rdcstr &val)
 {
   SDObject *ret = new SDObject(name, "string"_lit);
@@ -1117,7 +1188,13 @@ inline SDObject *makeSDString(const rdcinflexiblestr &name, const rdcstr &val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of a ResourceId");
+DOCUMENT(R"(Make a structured object as a ResourceId value.
+
+:param str name: The name of the object.
+:param ResourceId val: The ID which will be stored in the returned object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDResourceId(const rdcinflexiblestr &name, ResourceId val)
 {
   SDObject *ret = new SDObject(name, "ResourceId"_lit);
@@ -1127,7 +1204,17 @@ inline SDObject *makeSDResourceId(const rdcinflexiblestr &name, ResourceId val)
   return ret;
 }
 
-DOCUMENT("Make a structured object out of an enumeration value");
+DOCUMENT(R"(Make a structured object as an enum value.
+
+.. note::
+  The enum will be stored just as an integer value, but the string name of the enumeration value can
+  be set with :meth:`SDObject.SetCustomString` if desired.
+
+:param str name: The name of the object.
+:param int val: The integer value of the enum itself.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDEnum(const rdcinflexiblestr &name, uint32_t val)
 {
   SDObject *ret = new SDObject(name, "enum"_lit);
@@ -1137,7 +1224,14 @@ inline SDObject *makeSDEnum(const rdcinflexiblestr &name, uint32_t val)
   return ret;
 }
 
-DOCUMENT("Make an array-type structured object");
+DOCUMENT(R"(Make a structured object which is an array.
+
+The array will be created empty, and new members can be added using methods on :class:`SDObject`.
+
+:param str name: The name of the object.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDArray(const rdcinflexiblestr &name)
 {
   SDObject *ret = new SDObject(name, "array"_lit);
@@ -1145,7 +1239,15 @@ inline SDObject *makeSDArray(const rdcinflexiblestr &name)
   return ret;
 }
 
-DOCUMENT("Make an struct-type structured object");
+DOCUMENT(R"(Make a structured object which is a struct.
+
+The struct will be created empty, and new members can be added using methods on :class:`SDObject`.
+
+:param str name: The name of the object.
+:param str structtype: The typename of the struct.
+:return: The new object, owner by the caller.
+:rtype: SDObject
+)");
 inline SDObject *makeSDStruct(const rdcinflexiblestr &name, const rdcinflexiblestr &structtype)
 {
   SDObject *ret = new SDObject(name, structtype);
@@ -1218,7 +1320,10 @@ struct SDChunk : public SDObject
   DOCUMENT("The :class:`SDChunkMetaData` with the metadata for this chunk.");
   SDChunkMetaData metadata;
 
-  DOCUMENT("Create a deep copy of this chunk.");
+  DOCUMENT(R"(
+:return: A new deep copy of this chunk, which the caller owns.
+:rtype: SDChunk
+)");
   SDChunk *Duplicate() const
   {
     SDChunk *ret = new SDChunk();
@@ -1246,7 +1351,7 @@ protected:
 
 DECLARE_REFLECTION_STRUCT(SDChunk);
 
-DOCUMENT("A ``list`` of :class:`SDChunk` objects");
+DOCUMENT("INTERNAL: An array of SDChunk*, mapped to a pure list in python");
 struct StructuredChunkList : public rdcarray<SDChunk *>
 {
   StructuredChunkList() : rdcarray<SDChunk *>() {}
@@ -1283,7 +1388,7 @@ DECLARE_REFLECTION_STRUCT(StructuredChunkList);
 
 DECLARE_REFLECTION_STRUCT(bytebuf);
 
-DOCUMENT("A ``list`` of ``bytes`` objects");
+DOCUMENT("INTERNAL: An array of bytebuf*, mapped to a pure list of bytes in python");
 struct StructuredBufferList : public rdcarray<bytebuf *>
 {
   StructuredBufferList() : rdcarray<bytebuf *>() {}
@@ -1362,15 +1467,25 @@ public:
       delete buf;
   }
 
-  DOCUMENT("A ``list`` of :class:`SDChunk` objects with the chunks in order.");
+  DOCUMENT(R"(The chunks in the file in order.
+
+:type: List[SDChunk]
+)");
   StructuredChunkList chunks;
 
-  DOCUMENT("A ``list`` of serialised buffers stored as ``bytes`` objects");
+  DOCUMENT(R"(The buffers in the file, as referenced by the chunks in :data:`chunks`.
+
+:type: List[bytes]
+)");
   StructuredBufferList buffers;
 
   DOCUMENT("The version of this structured stream, typically only used internally.");
   uint64_t version = 0;
 
+  DOCUMENT(R"(Swaps the contents of this file with another.
+
+:param SDFile other: The other file to swap with.
+)");
   inline void Swap(SDFile &other)
   {
     chunks.swap(other.chunks);

renderdoc/api/replay/vk_pipestate.h

@@ -201,7 +201,7 @@ conversion.
   DOCUMENT(R"(For samplers - check if the border color is used in this Vulkan sampler.
 
 :return: ``True`` if the border color is used, ``False`` otherwise.
-:rtype: ``bool``
+:rtype: bool
 )");
   bool UseBorder() const
   {

renderdoc/core/remote_server.h

@@ -82,15 +82,15 @@ public:
 
   virtual rdcarray<GPUDevice> GetAvailableGPUs();
 
-  virtual int GetSectionCount();
+  virtual int32_t GetSectionCount();
 
-  virtual int FindSectionByName(const rdcstr &name);
+  virtual int32_t FindSectionByName(const rdcstr &name);
 
-  virtual int FindSectionByType(SectionType sectionType);
+  virtual int32_t FindSectionByType(SectionType sectionType);
 
-  virtual SectionProperties GetSectionProperties(int index);
+  virtual SectionProperties GetSectionProperties(int32_t index);
 
-  virtual bytebuf GetSectionContents(int index);
+  virtual bytebuf GetSectionContents(int32_t index);
 
   virtual bool WriteSection(const SectionProperties &props, const bytebuf &contents);
 

renderdoc/replay/capture_file.cpp

@@ -158,11 +158,11 @@ public:
 
   // ICaptureAccess
 
-  int GetSectionCount();
-  int FindSectionByName(const rdcstr &name);
-  int FindSectionByType(SectionType type);
-  SectionProperties GetSectionProperties(int index);
-  bytebuf GetSectionContents(int index);
+  int32_t GetSectionCount();
+  int32_t FindSectionByName(const rdcstr &name);
+  int32_t FindSectionByType(SectionType type);
+  SectionProperties GetSectionProperties(int32_t index);
+  bytebuf GetSectionContents(int32_t index);
   bool WriteSection(const SectionProperties &props, const bytebuf &contents);
 
   bool HasCallstacks();
@@ -677,7 +677,7 @@ Thumbnail CaptureFile::GetThumbnail(FileType type, uint32_t maxsize)
   return ret;
 }
 
-int CaptureFile::GetSectionCount()
+int32_t CaptureFile::GetSectionCount()
 {
   if(!m_RDC)
     return 0;
@@ -685,7 +685,7 @@ int CaptureFile::GetSectionCount()
   return m_RDC->NumSections();
 }
 
-int CaptureFile::FindSectionByName(const rdcstr &name)
+int32_t CaptureFile::FindSectionByName(const rdcstr &name)
 {
   if(!m_RDC)
     return -1;
@@ -693,7 +693,7 @@ int CaptureFile::FindSectionByName(const rdcstr &name)
   return m_RDC->SectionIndex(name);
 }
 
-int CaptureFile::FindSectionByType(SectionType type)
+int32_t CaptureFile::FindSectionByType(SectionType type)
 {
   if(!m_RDC)
     return -1;
@@ -701,7 +701,7 @@ int CaptureFile::FindSectionByType(SectionType type)
   return m_RDC->SectionIndex(type);
 }
 
-SectionProperties CaptureFile::GetSectionProperties(int index)
+SectionProperties CaptureFile::GetSectionProperties(int32_t index)
 {
   if(!m_RDC || index < 0 || index >= m_RDC->NumSections())
     return SectionProperties();
@@ -709,7 +709,7 @@ SectionProperties CaptureFile::GetSectionProperties(int index)
   return m_RDC->GetSectionProperties(index);
 }
 
-bytebuf CaptureFile::GetSectionContents(int index)
+bytebuf CaptureFile::GetSectionContents(int32_t index)
 {
   bytebuf ret;