From b9a2c32219daa00755a61859c0db1854c08875a1 Mon Sep 17 00:00:00 2001 From: Johnny Chen Date: Fri, 1 Jul 2011 22:14:07 +0000 Subject: [PATCH] Add some documentation blocks to SBTarget.h and use swig docstring feature to take advantage of them. Update modify-python-lldb.py to remove some 'residues' resulting from swigification. llvm-svn: 134269 --- lldb/include/lldb/API/SBTarget.h | 106 ++++++++++++++++++++-- lldb/scripts/Python/modify-python-lldb.py | 16 ++++ 2 files changed, 114 insertions(+), 8 deletions(-) diff --git a/lldb/include/lldb/API/SBTarget.h b/lldb/include/lldb/API/SBTarget.h index 88d064680faf..94051807204a 100644 --- a/lldb/include/lldb/API/SBTarget.h +++ b/lldb/include/lldb/API/SBTarget.h @@ -62,6 +62,9 @@ public: lldb::SBProcess GetProcess (); +#ifdef SWIG + %feature("autodoc", " +#endif //------------------------------------------------------------------ /// Launch a new process. /// @@ -115,6 +118,9 @@ public: /// @return /// A process object for the newly created process. //------------------------------------------------------------------ +#ifdef SWIG + ") Launch; +#endif lldb::SBProcess Launch (SBListener &listener, char const **argv, @@ -128,6 +134,9 @@ public: lldb::SBError& error); +#ifdef SWIG + %feature("autodoc", " +#endif //------------------------------------------------------------------ /// Launch a new process with sensible defaults. /// @@ -154,26 +163,107 @@ public: /// @return /// A process object for the newly created process. //------------------------------------------------------------------ +#ifdef SWIG + ") LaunchSimple; +#endif lldb::SBProcess LaunchSimple (const char **argv, const char **envp, const char *working_directory); +#ifdef SWIG + %feature("autodoc", " +#endif + //------------------------------------------------------------------ + /// Attach to process with pid. + /// + /// @param[in] listener + /// An optional listener that will receive all process events. + /// If \a listener is valid then \a listener will listen to all + /// process events. If not valid, then this target's debugger + /// (SBTarget::GetDebugger()) will listen to all process events. + /// + /// @param[in] pid + /// The process ID to attach to. + /// + /// @param[out] + /// An error explaining what went wrong if attach fails. + /// + /// @return + /// A process object for the attached process. + //------------------------------------------------------------------ +#ifdef SWIG + ") AttachToProcessWithID; +#endif lldb::SBProcess - AttachToProcessWithID (SBListener &listener, - lldb::pid_t pid, // The process ID to attach to - lldb::SBError& error); // An error explaining what went wrong if attach fails + AttachToProcessWithID (SBListener &listener, + lldb::pid_t pid, + lldb::SBError& error); +#ifdef SWIG + %feature("autodoc", " +#endif + //------------------------------------------------------------------ + /// Attach to process with name. + /// + /// @param[in] listener + /// An optional listener that will receive all process events. + /// If \a listener is valid then \a listener will listen to all + /// process events. If not valid, then this target's debugger + /// (SBTarget::GetDebugger()) will listen to all process events. + /// + /// @param[in] name + /// Basename of process to attach to. + /// + /// @param[in] wait_for + /// If true wait for a new instance of 'name' to be launched. + /// + /// @param[out] + /// An error explaining what went wrong if attach fails. + /// + /// @return + /// A process object for the attached process. + //------------------------------------------------------------------ +#ifdef SWIG + ") AttachToProcessWithName; +#endif lldb::SBProcess - AttachToProcessWithName (SBListener &listener, - const char *name, // basename of process to attach to - bool wait_for, // if true wait for a new instance of "name" to be launched - lldb::SBError& error); // An error explaining what went wrong if attach fails + AttachToProcessWithName (SBListener &listener, + const char *name, + bool wait_for, + lldb::SBError& error); +#ifdef SWIG + %feature("autodoc", " +#endif + //------------------------------------------------------------------ + /// Attach to process with name. + /// + /// @param[in] listener + /// An optional listener that will receive all process events. + /// If \a listener is valid then \a listener will listen to all + /// process events. If not valid, then this target's debugger + /// (SBTarget::GetDebugger()) will listen to all process events. + /// + /// @param[in] url + /// The url to connect to, e.g., 'connect://localhost:12345'. + /// + /// @param[in] plugin_name + /// The plugin name to be used; can be NULL. + /// + /// @param[out] + /// An error explaining what went wrong if the connect fails. + /// + /// @return + /// A process object for the connected process. + //------------------------------------------------------------------ +#ifdef SWIG + ") ConnectRemote; +#endif lldb::SBProcess ConnectRemote (SBListener &listener, const char *url, - const char *plugin_name, // Can be NULL + const char *plugin_name, SBError& error); lldb::SBFileSpec diff --git a/lldb/scripts/Python/modify-python-lldb.py b/lldb/scripts/Python/modify-python-lldb.py index 4d3b861e29c0..93d0bd446bdd 100644 --- a/lldb/scripts/Python/modify-python-lldb.py +++ b/lldb/scripts/Python/modify-python-lldb.py @@ -6,6 +6,12 @@ # objects, implements truth value testing for certain lldb objects, and adds a # global variable 'debugger_unique_id' which is initialized to 0. # +# As a cleanup step, it also removes the 'residues' from the autodoc features of +# swig. For an example, take a look at SBTarget.h header file, where we take +# advantage of the already existing C++-style headerdoc and make it the Python +# docstring for the same method. The 'residues' in this context include the +# '#endif' and the '#ifdef SWIG' lines. +# # It also calls SBDebugger.Initialize() to initialize the lldb debugger # subsystem. # @@ -19,6 +25,10 @@ else: # print "output_name is '" + output_name + "'" +# Residues to be removed. +c_endif_swig = "#endif" +c_ifdef_swig = "#ifdef SWIG" + # # lldb_iter() should appear before our first SB* class definition. # @@ -148,6 +158,12 @@ lldb_iter_defined = False; # value testing and the built-in operation bool(). state = NORMAL for line in content.splitlines(): + # Cleanse the lldb.py of the autodoc'ed residues. + if c_ifdef_swig in line or c_endif_swig in line: + continue + # Also remove the '\a ' substrings. + line = line.replace('\a ', '') + if state == NORMAL: match = class_pattern.search(line) # Inserts the lldb_iter() definition before the first class definition.