Author: Raphael Isemann Date: 2021-01-18T10:47:19+01:00 New Revision: f446fc5acf88fda676b5df1c04838f7244201d20
URL: https://github.com/llvm/llvm-project/commit/f446fc5acf88fda676b5df1c04838f7244201d20 DIFF: https://github.com/llvm/llvm-project/commit/f446fc5acf88fda676b5df1c04838f7244201d20.diff LOG: [lldb][docs] Resolve the remaining sphinx formatter warnings in the SB API docs With this patch there should no longer be any warnings when generating the SB API sphinx docs. Added: Modified: lldb/bindings/interface/SBAddress.i lldb/bindings/interface/SBBroadcaster.i lldb/bindings/interface/SBDebugger.i lldb/bindings/interface/SBFrame.i lldb/bindings/interface/SBModule.i lldb/bindings/interface/SBProcess.i lldb/bindings/interface/SBTarget.i lldb/bindings/interface/SBValue.i Removed: ################################################################################ diff --git a/lldb/bindings/interface/SBAddress.i b/lldb/bindings/interface/SBAddress.i index 694a7723e225..8e95d36e580d 100644 --- a/lldb/bindings/interface/SBAddress.i +++ b/lldb/bindings/interface/SBAddress.i @@ -109,18 +109,17 @@ public: An address might refer to code or data from an existing module, or it might refer to something on the stack or heap. The following functions will only return valid values if the address has been resolved to a code - or data address using 'void SBAddress::SetLoadAddress(...)' or - 'lldb::SBAddress SBTarget::ResolveLoadAddress (...)'.") GetSymbolContext; + or data address using :py:class:`SBAddress.SetLoadAddress' or + :py:class:`SBTarget.ResolveLoadAddress`.") GetSymbolContext; lldb::SBSymbolContext GetSymbolContext (uint32_t resolve_scope); %feature("docstring", " GetModule() and the following grab individual objects for a given address and are less efficient if you want more than one symbol related objects. - Use one of the following when you want multiple debug symbol related - objects for an address: - lldb::SBSymbolContext SBAddress::GetSymbolContext (uint32_t resolve_scope); - lldb::SBSymbolContext SBTarget::ResolveSymbolContextForAddress (const SBAddress &addr, uint32_t resolve_scope); + Use :py:class:`SBAddress.GetSymbolContext` or + :py:class:`SBTarget.ResolveSymbolContextForAddress` when you want multiple + debug symbol related objects for an address. One or more bits from the SymbolContextItem enumerations can be logically OR'ed together to more efficiently retrieve multiple symbol objects.") GetModule; lldb::SBModule diff --git a/lldb/bindings/interface/SBBroadcaster.i b/lldb/bindings/interface/SBBroadcaster.i index dd6de1feff42..e97d8f964bde 100644 --- a/lldb/bindings/interface/SBBroadcaster.i +++ b/lldb/bindings/interface/SBBroadcaster.i @@ -9,7 +9,9 @@ namespace lldb { %feature("docstring", -"Represents an entity which can broadcast events. A default broadcaster is +"Represents an entity which can broadcast events. + +A default broadcaster is associated with an SBCommandInterpreter, SBProcess, and SBTarget. For example, use :: diff --git a/lldb/bindings/interface/SBDebugger.i b/lldb/bindings/interface/SBDebugger.i index 78d737b48c23..cf4411980cc3 100644 --- a/lldb/bindings/interface/SBDebugger.i +++ b/lldb/bindings/interface/SBDebugger.i @@ -498,12 +498,12 @@ A tuple with the number of errors encountered by the interpreter, a boolean indicating whether quitting the interpreter was requested and another boolean set to True in case of a crash. -Example: +Example: :: -# Start an interactive lldb session from a script (with a valid debugger object -# created beforehand): -n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True, - False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter; + # Start an interactive lldb session from a script (with a valid debugger object + # created beforehand): + n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True, + False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter; %apply int& INOUT { int& num_errors }; %apply bool& INOUT { bool& quit_requested }; %apply bool& INOUT { bool& stopped_for_crash }; diff --git a/lldb/bindings/interface/SBFrame.i b/lldb/bindings/interface/SBFrame.i index 8ceb03bb7a18..047b090e8a61 100644 --- a/lldb/bindings/interface/SBFrame.i +++ b/lldb/bindings/interface/SBFrame.i @@ -13,30 +13,30 @@ namespace lldb { SBThread contains SBFrame(s). For example (from test/lldbutil.py), :: -def print_stacktrace(thread, string_buffer = False): - '''Prints a simple stack trace of this thread.''' - - ... - - for i in range(depth): - frame = thread.GetFrameAtIndex(i) - function = frame.GetFunction() - - load_addr = addrs[i].GetLoadAddress(target) - if not function: - file_addr = addrs[i].GetFileAddress() - start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress() - symbol_offset = file_addr - start_addr - print >> output, ' frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format( - num=i, addr=load_addr, mod=mods[i], symbol=symbols[i], offset=symbol_offset) - else: - print >> output, ' frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format( - num=i, addr=load_addr, mod=mods[i], - func='%s [inlined]' % funcs[i] if frame.IsInlined() else funcs[i], - file=files[i], line=lines[i], - args=get_args_as_string(frame, showFuncName=False) if not frame.IsInlined() else '()') - - ... + def print_stacktrace(thread, string_buffer = False): + '''Prints a simple stack trace of this thread.''' + + ... + + for i in range(depth): + frame = thread.GetFrameAtIndex(i) + function = frame.GetFunction() + + load_addr = addrs[i].GetLoadAddress(target) + if not function: + file_addr = addrs[i].GetFileAddress() + start_addr = frame.GetSymbol().GetStartAddress().GetFileAddress() + symbol_offset = file_addr - start_addr + print >> output, ' frame #{num}: {addr:#016x} {mod}`{symbol} + {offset}'.format( + num=i, addr=load_addr, mod=mods[i], symbol=symbols[i], offset=symbol_offset) + else: + print >> output, ' frame #{num}: {addr:#016x} {mod}`{func} at {file}:{line} {args}'.format( + num=i, addr=load_addr, mod=mods[i], + func='%s [inlined]' % funcs[i] if frame.IsInlined() else funcs[i], + file=files[i], line=lines[i], + args=get_args_as_string(frame, showFuncName=False) if not frame.IsInlined() else '()') + + ... And, :: @@ -247,20 +247,27 @@ public: %feature("docstring", " Get a lldb.SBValue for a variable path. - Variable paths can include access to pointer or instance members: + Variable paths can include access to pointer or instance members: :: + rect_ptr->origin.y pt.x - Pointer dereferences: + + Pointer dereferences: :: + *this->foo_ptr **argv - Address of: + + Address of: :: + &pt &my_array[3].x - Array accesses and treating pointers as arrays: + + Array accesses and treating pointers as arrays: :: + int_array[1] pt_ptr[22].x - Unlike EvaluateExpression() which returns lldb.SBValue objects + Unlike `EvaluateExpression()` which returns :py:class:`SBValue` objects with constant copies of the values at the time of evaluation, the result of this function is a value that will continue to track the current value of the value as execution progresses @@ -275,7 +282,7 @@ public: Find variables, register sets, registers, or persistent variables using the frame as the scope. - The version that doesn't supply a 'use_dynamic' value will use the + The version that doesn't supply a `use_dynamic` value will use the target's default.") FindValue; lldb::SBValue FindValue (const char *name, ValueType value_type); diff --git a/lldb/bindings/interface/SBModule.i b/lldb/bindings/interface/SBModule.i index d62d8b014b02..606c9a5bbd0c 100644 --- a/lldb/bindings/interface/SBModule.i +++ b/lldb/bindings/interface/SBModule.i @@ -204,15 +204,15 @@ public: GetCompileUnitAtIndex (uint32_t); %feature("docstring", " - Find compile units related to *this module and passed source + Find compile units related to this module and passed source file. @param[in] sb_file_spec - A lldb::SBFileSpec object that contains source file + A :py:class:`SBFileSpec` object that contains source file specification. @return - A lldb::SBSymbolContextList that gets filled in with all of + A :py:class:`SBSymbolContextList` that gets filled in with all of the symbol contexts for all the matches.") FindCompileUnits; lldb::SBSymbolContextList FindCompileUnits (const lldb::SBFileSpec &sb_file_spec); diff --git a/lldb/bindings/interface/SBProcess.i b/lldb/bindings/interface/SBProcess.i index 6f4a5db27eb9..e30b89d1ed39 100644 --- a/lldb/bindings/interface/SBProcess.i +++ b/lldb/bindings/interface/SBProcess.i @@ -244,67 +244,67 @@ public: %feature("autodoc", " Reads memory from the current process's address space and removes any traps that may have been inserted into the memory. It returns the byte - buffer in a Python string. Example: + buffer in a Python string. Example: :: - # Read 4 bytes from address 'addr' and assume error.Success() is True. - content = process.ReadMemory(addr, 4, error) - new_bytes = bytearray(content)") ReadMemory; + # Read 4 bytes from address 'addr' and assume error.Success() is True. + content = process.ReadMemory(addr, 4, error) + new_bytes = bytearray(content)") ReadMemory; size_t ReadMemory (addr_t addr, void *buf, size_t size, lldb::SBError &error); %feature("autodoc", " Writes memory to the current process's address space and maintains any - traps that might be present due to software breakpoints. Example: + traps that might be present due to software breakpoints. Example: :: - # Create a Python string from the byte array. - new_value = str(bytes) - result = process.WriteMemory(addr, new_value, error) - if not error.Success() or result != len(bytes): - print('SBProcess.WriteMemory() failed!')") WriteMemory; + # Create a Python string from the byte array. + new_value = str(bytes) + result = process.WriteMemory(addr, new_value, error) + if not error.Success() or result != len(bytes): + print('SBProcess.WriteMemory() failed!')") WriteMemory; size_t WriteMemory (addr_t addr, const void *buf, size_t size, lldb::SBError &error); %feature("autodoc", " Reads a NULL terminated C string from the current process's address space. It returns a python string of the exact length, or truncates the string if - the maximum character limit is reached. Example: + the maximum character limit is reached. Example: :: - # Read a C string of at most 256 bytes from address '0x1000' - error = lldb.SBError() - cstring = process.ReadCStringFromMemory(0x1000, 256, error) - if error.Success(): - print('cstring: ', cstring) - else - print('error: ', error)") ReadCStringFromMemory; + # Read a C string of at most 256 bytes from address '0x1000' + error = lldb.SBError() + cstring = process.ReadCStringFromMemory(0x1000, 256, error) + if error.Success(): + print('cstring: ', cstring) + else + print('error: ', error)") ReadCStringFromMemory; size_t ReadCStringFromMemory (addr_t addr, void *char_buf, size_t size, lldb::SBError &error); %feature("autodoc", " Reads an unsigned integer from memory given a byte size and an address. - Returns the unsigned integer that was read. Example: + Returns the unsigned integer that was read. Example: :: - # Read a 4 byte unsigned integer from address 0x1000 - error = lldb.SBError() - uint = ReadUnsignedFromMemory(0x1000, 4, error) - if error.Success(): - print('integer: %u' % uint) - else - print('error: ', error)") ReadUnsignedFromMemory; + # Read a 4 byte unsigned integer from address 0x1000 + error = lldb.SBError() + uint = ReadUnsignedFromMemory(0x1000, 4, error) + if error.Success(): + print('integer: %u' % uint) + else + print('error: ', error)") ReadUnsignedFromMemory; uint64_t ReadUnsignedFromMemory (addr_t addr, uint32_t byte_size, lldb::SBError &error); %feature("autodoc", " - Reads a pointer from memory from an address and returns the value. Example: + Reads a pointer from memory from an address and returns the value. Example: :: - # Read a pointer from address 0x1000 - error = lldb.SBError() - ptr = ReadPointerFromMemory(0x1000, error) - if error.Success(): - print('pointer: 0x%x' % ptr) - else - print('error: ', error)") ReadPointerFromMemory; + # Read a pointer from address 0x1000 + error = lldb.SBError() + ptr = ReadPointerFromMemory(0x1000, error) + if error.Success(): + print('pointer: 0x%x' % ptr) + else + print('error: ', error)") ReadPointerFromMemory; lldb::addr_t ReadPointerFromMemory (addr_t addr, lldb::SBError &error); @@ -412,11 +412,11 @@ public: %feature("autodoc", " Get information about the process. Valid process info will only be returned when the process is alive, - use IsValid() to check if the info returned is valid. + use IsValid() to check if the info returned is valid. :: - process_info = process.GetProcessInfo() - if process_info.IsValid(): - process_info.GetProcessID()") GetProcessInfo; + process_info = process.GetProcessInfo() + if process_info.IsValid(): + process_info.GetProcessID()") GetProcessInfo; lldb::SBProcessInfo GetProcessInfo(); diff --git a/lldb/bindings/interface/SBTarget.i b/lldb/bindings/interface/SBTarget.i index 3888d5a0dc55..f874726b42d8 100644 --- a/lldb/bindings/interface/SBTarget.i +++ b/lldb/bindings/interface/SBTarget.i @@ -16,7 +16,7 @@ SBTarget supports module, breakpoint, and watchpoint iterations. For example, :: for m in target.module_iter(): print m -produces: +produces: :: (x86_64) /Volumes/data/lldb/svn/trunk/test/python_api/lldbutil/iter/a.out (x86_64) /usr/lib/dyld @@ -208,30 +208,16 @@ public: %feature("docstring", " Launch a new process with sensible defaults. - @param[in] argv - The argument array. - - @param[in] envp - The environment array. - - @param[in] working_directory - The working directory to have the child process run in + :param argv: The argument array. + :param envp: The environment array. + :param working_directory: The working directory to have the child process run in + :return: The newly created process. + :rtype: SBProcess - Default: listener - Set to the target's debugger (SBTarget::GetDebugger()) + A pseudo terminal will be used as stdin/stdout/stderr. + No launch flags are passed and the target's debuger is used as a listener. - Default: launch_flags - Empty launch flags - - Default: stdin_path - Default: stdout_path - Default: stderr_path - A pseudo terminal will be used. - - @return - A process object for the newly created process. - - For example, + For example, :: process = target.LaunchSimple(['X', 'Y', 'Z'], None, os.getcwd()) @@ -389,16 +375,13 @@ public: FindModule (const lldb::SBFileSpec &file_spec); %feature("docstring", " - Find compile units related to *this target and passed source + Find compile units related to this target and passed source file. - @param[in] sb_file_spec - A lldb::SBFileSpec object that contains source file + :param sb_file_spec: A :py:class:`lldb::SBFileSpec` object that contains source file specification. - - @return - A lldb::SBSymbolContextList that gets filled in with all of - the symbol contexts for all the matches.") FindCompileUnits; + :return: The symbol contexts for all the matches. + :rtype: SBSymbolContextList") FindCompileUnits; lldb::SBSymbolContextList FindCompileUnits (const lldb::SBFileSpec &sb_file_spec); @@ -414,18 +397,18 @@ public: %feature("docstring", " Architecture data byte width accessor - @return - The size in 8-bit (host) bytes of a minimum addressable - unit from the Architecture's data bus") GetDataByteSize; + :return: The size in 8-bit (host) bytes of a minimum addressable unit from the Architecture's data bus. + + ") GetDataByteSize; uint32_t GetDataByteSize (); %feature("docstring", " - Architecture code byte width accessor + Architecture code byte width accessor. - @return - The size in 8-bit (host) bytes of a minimum addressable - unit from the Architecture's code bus") GetCodeByteSize; + :return: The size in 8-bit (host) bytes of a minimum addressable unit from the Architecture's code bus. + + ") GetCodeByteSize; uint32_t GetCodeByteSize (); @@ -446,17 +429,16 @@ public: %feature("docstring", " Find functions by name. - @param[in] name - The name of the function we are looking for. + :param name: The name of the function we are looking for. - @param[in] name_type_mask + :param name_type_mask: A logical OR of one or more FunctionNameType enum bits that indicate what kind of names should be used when doing the lookup. Bits include fully qualified names, base names, C++ methods, or ObjC selectors. See FunctionNameType for more details. - @return + :return: A lldb::SBSymbolContextList that gets filled in with all of the symbol contexts for all the matches.") FindFunctions; lldb::SBSymbolContextList @@ -694,41 +676,42 @@ public: @param[in] class_name This is the name of the class that implements a scripted resolver. - The class should have the following signature: - class Resolver: - def __init__(self, bkpt, extra_args): - # bkpt - the breakpoint for which this is the resolver. When - # the resolver finds an interesting address, call AddLocation - # on this breakpoint to add it. - # - # extra_args - an SBStructuredData that can be used to - # parametrize this instance. Same as the extra_args passed - # to BreakpointCreateFromScript. - - def __get_depth__ (self): - # This is optional, but if defined, you should return the - # depth at which you want the callback to be called. The - # available options are: - # lldb.eSearchDepthModule - # lldb.eSearchDepthCompUnit - # The default if you don't implement this method is - # eSearchDepthModule. - - def __callback__(self, sym_ctx): - # sym_ctx - an SBSymbolContext that is the cursor in the - # search through the program to resolve breakpoints. - # The sym_ctx will be filled out to the depth requested in - # __get_depth__. - # Look in this sym_ctx for new breakpoint locations, - # and if found use bkpt.AddLocation to add them. - # Note, you will only get called for modules/compile_units that - # pass the SearchFilter provided by the module_list & file_list - # passed into BreakpointCreateFromScript. - - def get_short_help(self): - # Optional, but if implemented return a short string that will - # be printed at the beginning of the break list output for the - # breakpoint. + The class should have the following signature: :: + + class Resolver: + def __init__(self, bkpt, extra_args): + # bkpt - the breakpoint for which this is the resolver. When + # the resolver finds an interesting address, call AddLocation + # on this breakpoint to add it. + # + # extra_args - an SBStructuredData that can be used to + # parametrize this instance. Same as the extra_args passed + # to BreakpointCreateFromScript. + + def __get_depth__ (self): + # This is optional, but if defined, you should return the + # depth at which you want the callback to be called. The + # available options are: + # lldb.eSearchDepthModule + # lldb.eSearchDepthCompUnit + # The default if you don't implement this method is + # eSearchDepthModule. + + def __callback__(self, sym_ctx): + # sym_ctx - an SBSymbolContext that is the cursor in the + # search through the program to resolve breakpoints. + # The sym_ctx will be filled out to the depth requested in + # __get_depth__. + # Look in this sym_ctx for new breakpoint locations, + # and if found use bkpt.AddLocation to add them. + # Note, you will only get called for modules/compile_units that + # pass the SearchFilter provided by the module_list & file_list + # passed into BreakpointCreateFromScript. + + def get_short_help(self): + # Optional, but if implemented return a short string that will + # be printed at the beginning of the break list output for the + # breakpoint. @param[in] extra_args This is an SBStructuredData object that will get passed to the @@ -908,11 +891,12 @@ public: %feature("docstring", " Disassemble a specified number of instructions starting at an address. - Parameters: - base_addr -- the address to start disassembly from - count -- the number of instructions to disassemble - flavor_string -- may be 'intel' or 'att' on x86 targets to specify that style of disassembly - Returns an SBInstructionList.") + + :param base_addr: the address to start disassembly from. + :param count: the number of instructions to disassemble. + :param flavor_string: may be 'intel' or 'att' on x86 targets to specify that style of disassembly. + :rtype: SBInstructionList + ") ReadInstructions; lldb::SBInstructionList ReadInstructions (lldb::SBAddress base_addr, uint32_t count); @@ -922,23 +906,25 @@ public: %feature("docstring", " Disassemble the bytes in a buffer and return them in an SBInstructionList. - Parameters: - base_addr -- used for symbolicating the offsets in the byte stream when disassembling - buf -- bytes to be disassembled - size -- (C++) size of the buffer - Returns an SBInstructionList.") + + :param base_addr: used for symbolicating the offsets in the byte stream when disassembling. + :param buf: bytes to be disassembled. + :param size: (C++) size of the buffer. + :rtype: SBInstructionList + ") GetInstructions; lldb::SBInstructionList GetInstructions (lldb::SBAddress base_addr, const void *buf, size_t size); %feature("docstring", " Disassemble the bytes in a buffer and return them in an SBInstructionList, with a supplied flavor. - Parameters: - base_addr -- used for symbolicating the offsets in the byte stream when disassembling - flavor -- may be 'intel' or 'att' on x86 targets to specify that style of disassembly - buf -- bytes to be disassembled - size -- (C++) size of the buffer - Returns an SBInstructionList.") + + :param base_addr: used for symbolicating the offsets in the byte stream when disassembling. + :param flavor: may be 'intel' or 'att' on x86 targets to specify that style of disassembly. + :param buf: bytes to be disassembled. + :param size: (C++) size of the buffer. + :rtype: SBInstructionList + ") GetInstructionsWithFlavor; lldb::SBInstructionList GetInstructionsWithFlavor (lldb::SBAddress base_addr, const char *flavor_string, const void *buf, size_t size); diff --git a/lldb/bindings/interface/SBValue.i b/lldb/bindings/interface/SBValue.i index 0bf5e4ccc648..928b6cffe464 100644 --- a/lldb/bindings/interface/SBValue.i +++ b/lldb/bindings/interface/SBValue.i @@ -379,22 +379,18 @@ public: Get an SBData wrapping what this SBValue points to. This method will dereference the current SBValue, if its - data type is a T* or T[], and extract item_count elements - of type T from it, copying their contents in an SBData. + data type is a `T\*` or `T[]`, and extract `item_count` elements + of type `T` from it, copying their contents in an :py:class:`SBData`. - @param[in] item_idx - The index of the first item to retrieve. For an array + :param item_idx: The index of the first item to retrieve. For an array this is equivalent to array[item_idx], for a pointer - to *(pointer + item_idx). In either case, the measurement - unit for item_idx is the sizeof(T) rather than the byte - - @param[in] item_count - How many items should be copied into the output. By default + to `\*(pointer + item_idx)`. In either case, the measurement + unit for item_idx is the `sizeof(T)` rather than the byte + :param item_count: How many items should be copied into the output. By default only one item is copied, but more can be asked for. - - @return - An SBData with the contents of the copied items, on success. - An empty SBData otherwise.") GetPointeeData; + :return: The contents of the copied items on success. An empty :py:class:`SBData` otherwise. + :rtype: SBData + ") GetPointeeData; lldb::SBData GetPointeeData (uint32_t item_idx = 0, uint32_t item_count = 1); _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
