[llvm-branch-commits] [lldb] acdc745 - [lldb][docs] Cleanup the Python doc strings for SB API classes
Raphael Isemann via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sun Jan 17 07:57:35 PST 2021
Author: Raphael Isemann
Date: 2021-01-17T16:51:07+01:00
New Revision: acdc74568927d47f94816e73b6e105c9460cc3e4
URL: https://github.com/llvm/llvm-project/commit/acdc74568927d47f94816e73b6e105c9460cc3e4
DIFF: https://github.com/llvm/llvm-project/commit/acdc74568927d47f94816e73b6e105c9460cc3e4.diff
LOG: [lldb][docs] Cleanup the Python doc strings for SB API classes
The first line of the doc string ends up on the SB API class summary at
the root page of the Python API web page of LLDB. Currently many of the
descriptions are missing or are several lines which makes the table really
hard to read.
This just adds the missing docstrings where possible and fixes the formatting
where necessary.
Added:
Modified:
lldb/bindings/interface/SBAttachInfo.i
lldb/bindings/interface/SBBreakpoint.i
lldb/bindings/interface/SBCommunication.i
lldb/bindings/interface/SBData.i
lldb/bindings/interface/SBExecutionContext.i
lldb/bindings/interface/SBFileSpecList.i
lldb/bindings/interface/SBFrame.i
lldb/bindings/interface/SBHostOS.i
lldb/bindings/interface/SBInstruction.i
lldb/bindings/interface/SBLanguageRuntime.i
lldb/bindings/interface/SBLaunchInfo.i
lldb/bindings/interface/SBLineEntry.i
lldb/bindings/interface/SBMemoryRegionInfoList.i
lldb/bindings/interface/SBModuleSpec.i
lldb/bindings/interface/SBPlatform.i
lldb/bindings/interface/SBQueue.i
lldb/bindings/interface/SBQueueItem.i
lldb/bindings/interface/SBReproducer.i
lldb/bindings/interface/SBStringList.i
lldb/bindings/interface/SBThreadPlan.i
lldb/bindings/interface/SBTrace.i
lldb/bindings/interface/SBTraceOptions.i
lldb/bindings/interface/SBType.i
lldb/bindings/interface/SBTypeEnumMember.i
lldb/bindings/interface/SBVariablesOptions.i
lldb/bindings/python/python-extensions.swig
Removed:
################################################################################
diff --git a/lldb/bindings/interface/SBAttachInfo.i b/lldb/bindings/interface/SBAttachInfo.i
index 3f4634e14619..9ac96e6dd7be 100644
--- a/lldb/bindings/interface/SBAttachInfo.i
+++ b/lldb/bindings/interface/SBAttachInfo.i
@@ -7,7 +7,9 @@
//===----------------------------------------------------------------------===//
namespace lldb {
-
+%feature("docstring",
+"Describes how to attach when calling :py:class:`SBTarget.Attach`."
+) SBAttachInfo;
class SBAttachInfo
{
public:
diff --git a/lldb/bindings/interface/SBBreakpoint.i b/lldb/bindings/interface/SBBreakpoint.i
index 983e9facfe20..37fcc7fbab48 100644
--- a/lldb/bindings/interface/SBBreakpoint.i
+++ b/lldb/bindings/interface/SBBreakpoint.i
@@ -313,6 +313,10 @@ public:
class SBBreakpointListImpl;
+
+%feature("docstring",
+"Represents a list of :py:class:`SBBreakpoint`."
+) SBBreakpointList;
class LLDB_API SBBreakpointList
{
public:
diff --git a/lldb/bindings/interface/SBCommunication.i b/lldb/bindings/interface/SBCommunication.i
index 87d3d0c9c5e4..8611e83e92ad 100644
--- a/lldb/bindings/interface/SBCommunication.i
+++ b/lldb/bindings/interface/SBCommunication.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Allows sending/receiving data."
+) SBCommunication;
class SBCommunication
{
public:
diff --git a/lldb/bindings/interface/SBData.i b/lldb/bindings/interface/SBData.i
index 3e74240329e0..a1fb4472cd23 100644
--- a/lldb/bindings/interface/SBData.i
+++ b/lldb/bindings/interface/SBData.i
@@ -9,6 +9,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a data buffer."
+) SBData;
class SBData
{
public:
diff --git a/lldb/bindings/interface/SBExecutionContext.i b/lldb/bindings/interface/SBExecutionContext.i
index 46968d04ae32..5fc5c0571182 100644
--- a/lldb/bindings/interface/SBExecutionContext.i
+++ b/lldb/bindings/interface/SBExecutionContext.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Describes the program context in which a command should be executed."
+) SBExecutionContext;
class SBExecutionContext
{
public:
diff --git a/lldb/bindings/interface/SBFileSpecList.i b/lldb/bindings/interface/SBFileSpecList.i
index 96641613f459..384dd4c4ae08 100644
--- a/lldb/bindings/interface/SBFileSpecList.i
+++ b/lldb/bindings/interface/SBFileSpecList.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a list of :py:class:`SBFileSpec`."
+) SBFileSpecList;
class SBFileSpecList
{
public:
diff --git a/lldb/bindings/interface/SBFrame.i b/lldb/bindings/interface/SBFrame.i
index b4e9b1c5f542..8ceb03bb7a18 100644
--- a/lldb/bindings/interface/SBFrame.i
+++ b/lldb/bindings/interface/SBFrame.i
@@ -10,6 +10,7 @@ namespace lldb {
%feature("docstring",
"Represents one of the stack frames associated with a thread.
+
SBThread contains SBFrame(s). For example (from test/lldbutil.py), ::
def print_stacktrace(thread, string_buffer = False):
diff --git a/lldb/bindings/interface/SBHostOS.i b/lldb/bindings/interface/SBHostOS.i
index 14f4186cb9f3..791fa5a2085e 100644
--- a/lldb/bindings/interface/SBHostOS.i
+++ b/lldb/bindings/interface/SBHostOS.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Provides information about the host system."
+) SBHostOS;
class SBHostOS
{
public:
diff --git a/lldb/bindings/interface/SBInstruction.i b/lldb/bindings/interface/SBInstruction.i
index d50a080fd045..e9e018b7deed 100644
--- a/lldb/bindings/interface/SBInstruction.i
+++ b/lldb/bindings/interface/SBInstruction.i
@@ -13,6 +13,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a (machine language) instruction."
+) SBInstruction;
class SBInstruction
{
public:
diff --git a/lldb/bindings/interface/SBLanguageRuntime.i b/lldb/bindings/interface/SBLanguageRuntime.i
index f28170b9ce77..244c57048e64 100644
--- a/lldb/bindings/interface/SBLanguageRuntime.i
+++ b/lldb/bindings/interface/SBLanguageRuntime.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Utility functions for :py:class:`LanguageType`"
+) SBLanguageRuntime;
class SBLanguageRuntime
{
public:
diff --git a/lldb/bindings/interface/SBLaunchInfo.i b/lldb/bindings/interface/SBLaunchInfo.i
index 1de89b58b272..d76656ddd493 100644
--- a/lldb/bindings/interface/SBLaunchInfo.i
+++ b/lldb/bindings/interface/SBLaunchInfo.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Describes how a target or program should be launched."
+) SBLaunchInfo;
class SBLaunchInfo
{
public:
diff --git a/lldb/bindings/interface/SBLineEntry.i b/lldb/bindings/interface/SBLineEntry.i
index a61d360c96f9..24f25ed1b4e5 100644
--- a/lldb/bindings/interface/SBLineEntry.i
+++ b/lldb/bindings/interface/SBLineEntry.i
@@ -10,7 +10,9 @@ namespace lldb {
%feature("docstring",
"Specifies an association with a contiguous range of instructions and
-a source file location. :py:class:`SBCompileUnit` contains SBLineEntry(s). For example, ::
+a source file location.
+
+:py:class:`SBCompileUnit` contains SBLineEntry(s). For example, ::
for lineEntry in compileUnit:
print('line entry: %s:%d' % (str(lineEntry.GetFileSpec()),
diff --git a/lldb/bindings/interface/SBMemoryRegionInfoList.i b/lldb/bindings/interface/SBMemoryRegionInfoList.i
index e408fc0f88b8..c2e74f1cd0dc 100644
--- a/lldb/bindings/interface/SBMemoryRegionInfoList.i
+++ b/lldb/bindings/interface/SBMemoryRegionInfoList.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a list of :py:class:`SBMemoryRegionInfo`."
+) SBMemoryRegionInfoList;
class SBMemoryRegionInfoList
{
public:
diff --git a/lldb/bindings/interface/SBModuleSpec.i b/lldb/bindings/interface/SBModuleSpec.i
index 64d0aa641a77..8b4c6a92160a 100644
--- a/lldb/bindings/interface/SBModuleSpec.i
+++ b/lldb/bindings/interface/SBModuleSpec.i
@@ -95,6 +95,9 @@ public:
};
+%feature("docstring",
+"Represents a list of :py:class:`SBModuleSpec`."
+) SBModuleSpecList;
class SBModuleSpecList
{
public:
diff --git a/lldb/bindings/interface/SBPlatform.i b/lldb/bindings/interface/SBPlatform.i
index 270aec04a2e2..65615be7a361 100644
--- a/lldb/bindings/interface/SBPlatform.i
+++ b/lldb/bindings/interface/SBPlatform.i
@@ -9,6 +9,9 @@
namespace lldb {
+%feature("docstring",
+"Describes how :py:class:`SBPlatform.ConnectRemote` connects to a remote platform."
+) SBPlatformConnectOptions;
class SBPlatformConnectOptions
{
public:
@@ -42,6 +45,9 @@ public:
SetLocalCacheDirectory(const char *path);
};
+%feature("docstring",
+"Represents a shell command that can be run by :py:class:`SBPlatform.Run`."
+) SBPlatformShellCommand;
class SBPlatformShellCommand
{
public:
diff --git a/lldb/bindings/interface/SBQueue.i b/lldb/bindings/interface/SBQueue.i
index f209d59f1bf9..9f2ec56b241c 100644
--- a/lldb/bindings/interface/SBQueue.i
+++ b/lldb/bindings/interface/SBQueue.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a libdispatch queue in the process."
+) SBQueue;
class SBQueue
{
public:
diff --git a/lldb/bindings/interface/SBQueueItem.i b/lldb/bindings/interface/SBQueueItem.i
index 089771e80378..2270d958e17d 100644
--- a/lldb/bindings/interface/SBQueueItem.i
+++ b/lldb/bindings/interface/SBQueueItem.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"This class represents an item in an :py:class:`SBQueue`."
+) SBQueueItem;
class SBQueueItem
{
public:
diff --git a/lldb/bindings/interface/SBReproducer.i b/lldb/bindings/interface/SBReproducer.i
index 7c9b007db3c0..bc9a5bab3cfa 100644
--- a/lldb/bindings/interface/SBReproducer.i
+++ b/lldb/bindings/interface/SBReproducer.i
@@ -7,6 +7,10 @@
//===----------------------------------------------------------------------===//
namespace lldb {
+
+%feature("docstring",
+"Controls LLDB's reproducer functionality."
+) SBReproducer;
class SBReproducer
{
public:
diff --git a/lldb/bindings/interface/SBStringList.i b/lldb/bindings/interface/SBStringList.i
index c8e1e357ed2b..d80ae9f9c5b9 100644
--- a/lldb/bindings/interface/SBStringList.i
+++ b/lldb/bindings/interface/SBStringList.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a list of strings."
+) SBStringList;
class SBStringList
{
public:
diff --git a/lldb/bindings/interface/SBThreadPlan.i b/lldb/bindings/interface/SBThreadPlan.i
index 2003c6fdee3a..94ae1a42dd3b 100644
--- a/lldb/bindings/interface/SBThreadPlan.i
+++ b/lldb/bindings/interface/SBThreadPlan.i
@@ -18,8 +18,8 @@ namespace lldb {
%feature("docstring",
"Represents a plan for the execution control of a given thread.
-See also SBThread and SBFrame."
-) SBThread;
+See also :py:class:`SBThread` and :py:class:`SBFrame`."
+) SBThreadPlan;
class SBThreadPlan
{
@@ -95,7 +95,7 @@ public:
%feature("docstring", "Return whether this plan will ask to stop other threads when it runs.") GetStopOthers;
bool
GetStopOthers();
-
+
%feature("docstring", "Set whether this plan will ask to stop other threads when it runs.") GetStopOthers;
void
SetStopOthers(bool stop_others);
diff --git a/lldb/bindings/interface/SBTrace.i b/lldb/bindings/interface/SBTrace.i
index a4cb2667ec10..6d4b7e6be27d 100644
--- a/lldb/bindings/interface/SBTrace.i
+++ b/lldb/bindings/interface/SBTrace.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Represents a processor trace."
+) SBTrace;
class LLDB_API SBTrace {
public:
SBTrace();
diff --git a/lldb/bindings/interface/SBTraceOptions.i b/lldb/bindings/interface/SBTraceOptions.i
index ce17af5376ca..4a1878b5b76f 100644
--- a/lldb/bindings/interface/SBTraceOptions.i
+++ b/lldb/bindings/interface/SBTraceOptions.i
@@ -8,6 +8,11 @@
namespace lldb {
+%feature("docstring",
+"Represents the possible options when doing processor tracing.
+
+See :py:class:`SBProcess.StartTrace`."
+) SBTraceOptions;
class LLDB_API SBTraceOptions {
public:
SBTraceOptions();
diff --git a/lldb/bindings/interface/SBType.i b/lldb/bindings/interface/SBType.i
index a6d61bdbb54f..bcf4397b8c58 100644
--- a/lldb/bindings/interface/SBType.i
+++ b/lldb/bindings/interface/SBType.i
@@ -9,7 +9,7 @@
namespace lldb {
%feature("docstring",
-"Represents a member of a type in lldb.") SBTypeMember;
+"Represents a member of a type.") SBTypeMember;
class SBTypeMember
{
@@ -60,6 +60,9 @@ protected:
std::unique_ptr<lldb_private::TypeMemberImpl> m_opaque_ap;
};
+%feature("docstring",
+"Represents a member function of a type."
+) SBTypeMemberFunction;
class SBTypeMemberFunction
{
public:
@@ -431,8 +434,9 @@ public:
};
%feature("docstring",
-"Represents a list of :py:class:`SBType` s. The FindTypes() method of
-:py:class:`SBTarget`/:py:class:`SBModule` returns a SBTypeList.
+"Represents a list of :py:class:`SBType` s.
+
+The FindTypes() method of :py:class:`SBTarget`/:py:class:`SBModule` returns a SBTypeList.
SBTypeList supports :py:class:`SBType` iteration. For example,
diff --git a/lldb/bindings/interface/SBTypeEnumMember.i b/lldb/bindings/interface/SBTypeEnumMember.i
index e26ac4d00b8c..b41901027245 100644
--- a/lldb/bindings/interface/SBTypeEnumMember.i
+++ b/lldb/bindings/interface/SBTypeEnumMember.i
@@ -73,6 +73,7 @@ protected:
%feature("docstring",
"Represents a list of SBTypeEnumMembers.
+
SBTypeEnumMemberList supports SBTypeEnumMember iteration.
It also supports [] access either by index, or by enum
element name by doing: ::
diff --git a/lldb/bindings/interface/SBVariablesOptions.i b/lldb/bindings/interface/SBVariablesOptions.i
index 362f7159d7d2..dfdc8cf5df68 100644
--- a/lldb/bindings/interface/SBVariablesOptions.i
+++ b/lldb/bindings/interface/SBVariablesOptions.i
@@ -8,6 +8,9 @@
namespace lldb {
+%feature("docstring",
+"Describes which variables should be returned from :py:class:`SBFrame.GetVariables`."
+) SBVariablesOptions;
class SBVariablesOptions
{
public:
diff --git a/lldb/bindings/python/python-extensions.swig b/lldb/bindings/python/python-extensions.swig
index c899768a6fdd..b98b0d458f0c 100644
--- a/lldb/bindings/python/python-extensions.swig
+++ b/lldb/bindings/python/python-extensions.swig
@@ -290,6 +290,7 @@ class declaration(object):
self.col = col
class value_iter(object):
+ '''Allows iterating over the children of an :py:class:`SBValue`.'''
def __iter__(self):
return self
@@ -311,10 +312,10 @@ class value_iter(object):
self.length = self.sbvalue.GetNumChildren()
class value(object):
- '''A class designed to wrap :py:class:`SBValue` objects so the resulting object
- can be used as a variable would be in code. So if you have a Point structure
- variable in your code in the current frame named "pt", you can initialize an instance
- of this class with it: ::
+ '''Wraps :py:class:`SBValue` objects so the resulting object can be used as a variable would be in code.
+
+ So if you have a Point structure variable in your code in the current frame named "pt",
+ you can initialize an instance of this class with it: ::
pt = lldb.value(lldb.frame.FindVariable("pt"))
print pt
More information about the llvm-branch-commits
mailing list