From 2a812bdc70c6153f41907db056e348d9b322f01c Mon Sep 17 00:00:00 2001 From: Michael Buch Date: Wed, 26 Oct 2022 14:40:34 +0100 Subject: [PATCH] [lldb][Docs][NFC] Fix sphinx warnings/errors for LLDB docs Ran `ninja docs-lldb-html` and made sure the docs are fixed. Differential Revision: https://reviews.llvm.org/D136766 --- lldb/bindings/interface/SBModule.i | 5 ++++- lldb/bindings/interface/SBTarget.i | 2 +- lldb/bindings/interface/SBType.i | 4 ++-- lldb/docs/resources/build.rst | 2 +- lldb/docs/resources/test.rst | 18 ++++++++---------- lldb/docs/use/intel_pt.rst | 4 ++-- 6 files changed, 18 insertions(+), 17 deletions(-) diff --git a/lldb/bindings/interface/SBModule.i b/lldb/bindings/interface/SBModule.i index bda602d..de476f7 100644 --- a/lldb/bindings/interface/SBModule.i +++ b/lldb/bindings/interface/SBModule.i @@ -137,8 +137,11 @@ public: void Clear(); - %feature("docstring", "Check if the module is file backed. + %feature("docstring", " + Check if the module is file backed. + @return + True, if the module is backed by an object file on disk. False, if the module is backed by an object file in memory.") IsFileBacked; bool diff --git a/lldb/bindings/interface/SBTarget.i b/lldb/bindings/interface/SBTarget.i index a6a7649..e887762 100644 --- a/lldb/bindings/interface/SBTarget.i +++ b/lldb/bindings/interface/SBTarget.i @@ -947,7 +947,7 @@ public: %feature("docstring", " Returns true if the module has been loaded in this `SBTarget`. A module can be loaded either by the dynamic loader or by being manually - added to the target (see `SBTarget.AddModule` and the `target module add` command). + added to the target (see `SBTarget.AddModule` and the ``target module add`` command). :rtype: bool ") IsLoaded; diff --git a/lldb/bindings/interface/SBType.i b/lldb/bindings/interface/SBType.i index ba33f92..5bead82 100644 --- a/lldb/bindings/interface/SBType.i +++ b/lldb/bindings/interface/SBType.i @@ -229,7 +229,7 @@ public: function returns ``0``. * C++: Same as in C. * Objective-C: Same as in C. For Objective-C classes this always returns - `0`` as the actual size depends on runtime information. + ``0`` as the actual size depends on runtime information. ") GetByteSize; uint64_t GetByteSize(); @@ -506,7 +506,7 @@ public: Language-specific behaviour: - * C: Returns a constant-size array `T[size]` for any non-void type. + * C: Returns a constant-size array ``T[size]`` for any non-void type. * C++: Same as in C. * Objective-C: Same as in C. diff --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst index c44bdee..36b61bc 100644 --- a/lldb/docs/resources/build.rst +++ b/lldb/docs/resources/build.rst @@ -99,7 +99,7 @@ Windows or even write new tests at all, PTVS is an indispensable debugging extension to VS that enables full editing and debugging support for Python (including mixed native/managed debugging). -* `SWIG for Windows _` +* `SWIG for Windows `_ The steps outlined here describes how to set up your system and install the required dependencies such that they can be found when needed during the build diff --git a/lldb/docs/resources/test.rst b/lldb/docs/resources/test.rst index 2ecce85..f912859 100644 --- a/lldb/docs/resources/test.rst +++ b/lldb/docs/resources/test.rst @@ -229,7 +229,7 @@ good testing practices. time (e.g., C and C++) there is also usually no process necessary to test the `SBType`-related parts of the API. With those languages it's also possible to test `SBValue` by running expressions with - `SBTarget.EvaluateExpression` or the `expect_expr` testing utility. + `SBTarget.EvaluateExpression` or the ``expect_expr`` testing utility. Functionality that always requires a running process is everything that tests the `SBProcess`, `SBThread`, and `SBFrame` classes. The same is true @@ -315,27 +315,27 @@ A better way to write the test above would be using LLDB's testing function self.expect_expr("2 + 2", result_value="0") **Prefer using specific asserts over the generic assertTrue/assertFalse.**. - The `self.assertTrue`/`self.assertFalse` functions should always be your + The ``self.assertTrue``/``self.assertFalse`` functions should always be your last option as they give non-descriptive error messages. The test class has - several expressive asserts such as `self.assertIn` that automatically + several expressive asserts such as ``self.assertIn`` that automatically generate an explanation how the received values differ from the expected - ones. Check the documentation of Python's `unittest` module to see what + ones. Check the documentation of Python's ``unittest`` module to see what asserts are available. LLDB also has a few custom asserts that are tailored to our own data types. +-----------------------------------------------+-----------------------------------------------------------------+ -| **Assert** | **Description** | +| **Assert** | **Description** | +-----------------------------------------------+-----------------------------------------------------------------+ -| ``assertSuccess`` | Assert that an ``lldb.SBError`` is in the "success" state. | +| ``assertSuccess`` | Assert that an ``lldb.SBError`` is in the "success" state. | +-----------------------------------------------+-----------------------------------------------------------------+ -| ``assertState`` | Assert that two states (``lldb.eState*``) are equal. | +| ``assertState`` | Assert that two states (``lldb.eState*``) are equal. | +-----------------------------------------------+-----------------------------------------------------------------+ | ``assertStopReason`` | Assert that two stop reasons (``lldb.eStopReason*``) are equal. | +-----------------------------------------------+-----------------------------------------------------------------+ If you can't find a specific assert that fits your needs and you fall back to a generic assert, make sure you put useful information into the assert's - `msg` argument that helps explain the failure. + ``msg`` argument that helps explain the failure. :: @@ -599,8 +599,6 @@ line to your ``~/.pdbrc``: alias lldb self.dbg.HandleCommand("%*") -:: - Debugging Test Failures on Windows `````````````````````````````````` diff --git a/lldb/docs/use/intel_pt.rst b/lldb/docs/use/intel_pt.rst index 3d615e3..694615c 100644 --- a/lldb/docs/use/intel_pt.rst +++ b/lldb/docs/use/intel_pt.rst @@ -39,8 +39,8 @@ decoder library [LibIPT library](https://github.com/intel/libipt). $ cd libipt-build $ make -This will generate a few files in the `/lib` -and `/libipt/include` directories. +This will generate a few files in the ``/lib`` +and ``/libipt/include`` directories. Configure and build LLDB with Intel PT support -- 2.7.4