diff options
133 files changed, 3307 insertions, 3648 deletions
diff --git a/lldb/docs/doxygen.cfg.in b/lldb/docs/doxygen.cfg.in index 725a26f2a03..0c206605185 100644 --- a/lldb/docs/doxygen.cfg.in +++ b/lldb/docs/doxygen.cfg.in @@ -137,7 +137,7 @@ SHORT_NAMES = NO # comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.) -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # If the QT_AUTOBRIEF tag is set to YES then Doxygen will # interpret the first line (until the first dot) of a Qt-style @@ -145,7 +145,7 @@ JAVADOC_AUTOBRIEF = NO # will behave just like regular Qt-style comments (thus requiring # an explicit \brief command for a brief description.) -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen # treat a multi-line C++ special comment block (i.e. a block of //! or /// diff --git a/lldb/include/lldb/Breakpoint/Breakpoint.h b/lldb/include/lldb/Breakpoint/Breakpoint.h index 57eb2adce79..ec4bc946280 100644 --- a/lldb/include/lldb/Breakpoint/Breakpoint.h +++ b/lldb/include/lldb/Breakpoint/Breakpoint.h @@ -33,8 +33,8 @@ namespace lldb_private { //---------------------------------------------------------------------- -/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" -/// @brief Class that manages logical breakpoint setting. +/// @class Breakpoint Breakpoint.h "lldb/Breakpoint/Breakpoint.h" Class that +/// manages logical breakpoint setting. //---------------------------------------------------------------------- //---------------------------------------------------------------------- @@ -42,33 +42,28 @@ namespace lldb_private { /// A breakpoint has four main parts, a filter, a resolver, the list of /// breakpoint /// locations that have been determined for the filter/resolver pair, and -/// finally -/// a set of options for the breakpoint. +/// finally a set of options for the breakpoint. /// /// \b Filter: -/// This is an object derived from SearchFilter. It manages the search -/// for breakpoint location matches through the symbols in the module list of -/// the target -/// that owns it. It also filters out locations based on whatever logic it -/// wants. +/// This is an object derived from SearchFilter. It manages the search for +/// breakpoint location matches through the symbols in the module list of the +/// target that owns it. It also filters out locations based on whatever +/// logic it wants. /// /// \b Resolver: -/// This is an object derived from BreakpointResolver. It provides a -/// callback to the filter that will find breakpoint locations. How it does -/// this is +/// This is an object derived from BreakpointResolver. It provides a callback +/// to the filter that will find breakpoint locations. How it does this is /// determined by what kind of resolver it is. /// /// The Breakpoint class also provides constructors for the common breakpoint -/// cases -/// which make the appropriate filter and resolver for you. +/// cases which make the appropriate filter and resolver for you. /// /// \b Location List: -/// This stores the breakpoint locations that have been determined -/// to date. For a given breakpoint, there will be only one location with a -/// given -/// address. Adding a location at an already taken address will just return the -/// location -/// already at that address. Locations can be looked up by ID, or by address. +/// This stores the breakpoint locations that have been determined to date. +/// For a given breakpoint, there will be only one location with a given +/// address. Adding a location at an already taken address will just return +/// the location already at that address. Locations can be looked up by ID, +/// or by address. /// /// \b Options: /// This includes: @@ -77,25 +72,17 @@ namespace lldb_private { /// \b Callback /// \b Condition /// Note, these options can be set on the breakpoint, and they can also be set -/// on the -/// individual locations. The options set on the breakpoint take precedence -/// over the -/// options set on the individual location. -/// So for instance disabling the breakpoint will cause NONE of the locations to -/// get hit. -/// But if the breakpoint is enabled, then the location's enabled state will be -/// checked -/// to determine whether to insert that breakpoint location. +/// on the individual locations. The options set on the breakpoint take +/// precedence over the options set on the individual location. So for +/// instance disabling the breakpoint will cause NONE of the locations to get +/// hit. But if the breakpoint is enabled, then the location's enabled state +/// will be checked to determine whether to insert that breakpoint location. /// Similarly, if the breakpoint condition says "stop", we won't check the -/// location's condition. -/// But if the breakpoint condition says "continue", then we will check the -/// location for whether -/// to actually stop or not. -/// One subtle point worth observing here is that you don't actually stop at a -/// Breakpoint, you -/// always stop at one of its locations. So the "should stop" tests are done by -/// the location, -/// not by the breakpoint. +/// location's condition. But if the breakpoint condition says "continue", +/// then we will check the location for whether to actually stop or not. One +/// subtle point worth observing here is that you don't actually stop at a +/// Breakpoint, you always stop at one of its locations. So the "should stop" +/// tests are done by the location, not by the breakpoint. //---------------------------------------------------------------------- class Breakpoint : public std::enable_shared_from_this<Breakpoint>, public Stoppoint { @@ -103,8 +90,8 @@ public: static const ConstString &GetEventIdentifier(); //------------------------------------------------------------------ - /// An enum specifying the match style for breakpoint settings. At - /// present only used for function name style breakpoints. + /// An enum specifying the match style for breakpoint settings. At present + /// only used for function name style breakpoints. //------------------------------------------------------------------ typedef enum { Exact, Regexp, Glob } MatchType; @@ -191,9 +178,9 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is not virtual since there should be no reason to subclass - /// breakpoints. The varieties of breakpoints are specified instead by - /// providing different resolvers & filters. + /// The destructor is not virtual since there should be no reason to + /// subclass breakpoints. The varieties of breakpoints are specified + /// instead by providing different resolvers & filters. //------------------------------------------------------------------ ~Breakpoint() override; @@ -202,8 +189,7 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Tell whether this breakpoint is an "internal" breakpoint. - /// @return + /// Tell whether this breakpoint is an "internal" breakpoint. @return /// Returns \b true if this is an internal breakpoint, \b false otherwise. //------------------------------------------------------------------ bool IsInternal() const; @@ -219,8 +205,8 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Tell this breakpoint to clear all its breakpoint sites. Done - /// when the process holding the breakpoint sites is destroyed. + /// Tell this breakpoint to clear all its breakpoint sites. Done when the + /// process holding the breakpoint sites is destroyed. //------------------------------------------------------------------ void ClearAllBreakpointSites(); @@ -231,8 +217,8 @@ public: void ResolveBreakpoint(); //------------------------------------------------------------------ - /// Tell this breakpoint to scan a given module list and resolve any - /// new locations that match the breakpoint's specifications. + /// Tell this breakpoint to scan a given module list and resolve any new + /// locations that match the breakpoint's specifications. /// /// @param[in] module_list /// The list of modules to look in for new locations. @@ -245,8 +231,8 @@ public: bool send_event = true); //------------------------------------------------------------------ - /// Tell this breakpoint to scan a given module list and resolve any - /// new locations that match the breakpoint's specifications. + /// Tell this breakpoint to scan a given module list and resolve any new + /// locations that match the breakpoint's specifications. /// /// @param[in] changed_modules /// The list of modules to look in for new locations. @@ -274,9 +260,9 @@ public: bool delete_locations = false); //------------------------------------------------------------------ - /// Tells the breakpoint the old module \a old_module_sp has been - /// replaced by new_module_sp (usually because the underlying file has been - /// rebuilt, and the old version is gone.) + /// Tells the breakpoint the old module \a old_module_sp has been replaced + /// by new_module_sp (usually because the underlying file has been rebuilt, + /// and the old version is gone.) /// /// @param[in] old_module_sp /// The old module that is going away. @@ -292,8 +278,8 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Add a location to the breakpoint's location list. This is only meant - /// to be called by the breakpoint's resolver. FIXME: how do I ensure that? + /// Add a location to the breakpoint's location list. This is only meant to + /// be called by the breakpoint's resolver. FIXME: how do I ensure that? /// /// @param[in] addr /// The Address specifying the new location. @@ -359,12 +345,12 @@ public: /// Removes all invalid breakpoint locations. /// /// Removes all breakpoint locations with architectures that aren't - /// compatible with \a arch. Also remove any breakpoint locations - /// with whose locations have address where the section has been - /// deleted (module and object files no longer exist). + /// compatible with \a arch. Also remove any breakpoint locations with whose + /// locations have address where the section has been deleted (module and + /// object files no longer exist). /// - /// This is typically used after the process calls exec, or anytime - /// the architecture of the target changes. + /// This is typically used after the process calls exec, or anytime the + /// architecture of the target changes. /// /// @param[in] arch /// If valid, check the module in each breakpoint to make sure @@ -403,8 +389,7 @@ public: uint32_t GetIgnoreCount() const; //------------------------------------------------------------------ - /// Return the current hit count for all locations. - /// @return + /// Return the current hit count for all locations. @return /// The current hit count for all locations. //------------------------------------------------------------------ uint32_t GetHitCount() const; @@ -422,7 +407,8 @@ public: bool IsOneShot() const; //------------------------------------------------------------------ - /// If \a auto_continue is \b true, breakpoint will auto-continue when on hit. + /// If \a auto_continue is \b true, breakpoint will auto-continue when on + /// hit. //------------------------------------------------------------------ void SetAutoContinue(bool auto_continue); @@ -508,8 +494,8 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Return the number of breakpoint locations that have resolved to - /// actual breakpoint sites. + /// Return the number of breakpoint locations that have resolved to actual + /// breakpoint sites. /// /// @return /// The number locations resolved breakpoint sites. @@ -541,10 +527,9 @@ public: //------------------------------------------------------------------ /// Set the "kind" description for a breakpoint. If the breakpoint is hit - /// the stop info will show this "kind" description instead of the breakpoint - /// number. Mostly useful for internal breakpoints, where the breakpoint - /// number - /// doesn't have meaning to the user. + /// the stop info will show this "kind" description instead of the + /// breakpoint number. Mostly useful for internal breakpoints, where the + /// breakpoint number doesn't have meaning to the user. /// /// @param[in] kind /// New "kind" description. @@ -574,10 +559,9 @@ public: //------------------------------------------------------------------ /// Find breakpoint locations which match the (filename, line_number) - /// description. - /// The breakpoint location collection is to be filled with the matching - /// locations. - /// It should be initialized with 0 size by the API client. + /// description. The breakpoint location collection is to be filled with the + /// matching locations. It should be initialized with 0 size by the API + /// client. /// /// @return /// True if there is a match @@ -661,13 +645,12 @@ public: /// Set a pre-condition filter that overrides all user provided /// filters/callbacks etc. /// - /// Used to define fancy breakpoints that can do dynamic hit detection without - /// taking up the condition slot - - /// which really belongs to the user anyway... + /// Used to define fancy breakpoints that can do dynamic hit detection + /// without taking up the condition slot - which really belongs to the user + /// anyway... /// - /// The Precondition should not continue the target, it should return true if - /// the condition says to stop and - /// false otherwise. + /// The Precondition should not continue the target, it should return true + /// if the condition says to stop and false otherwise. /// //------------------------------------------------------------------ void SetPrecondition(BreakpointPreconditionSP precondition_sp) { @@ -706,10 +689,9 @@ protected: //------------------------------------------------------------------ /// Constructors and Destructors /// Only the Target can make a breakpoint, and it owns the breakpoint - /// lifespans. - /// The constructor takes a filter and a resolver. Up in Target there are - /// convenience - /// variants that make breakpoints for some common cases. + /// lifespans. The constructor takes a filter and a resolver. Up in Target + /// there are convenience variants that make breakpoints for some common + /// cases. /// /// @param[in] target /// The target in which the breakpoint will be set. diff --git a/lldb/include/lldb/Breakpoint/BreakpointList.h b/lldb/include/lldb/Breakpoint/BreakpointList.h index 9f38f8aa120..f4c013d41cc 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointList.h +++ b/lldb/include/lldb/Breakpoint/BreakpointList.h @@ -23,7 +23,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointList BreakpointList.h "lldb/Breakpoint/BreakpointList.h" -/// @brief This class manages a list of breakpoints. +/// This class manages a list of breakpoints. //---------------------------------------------------------------------- //---------------------------------------------------------------------- @@ -91,7 +91,8 @@ public: lldb::BreakpointSP GetBreakpointAtIndex(size_t i); //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint with index \a i, const version + /// Returns a shared pointer to the breakpoint with index \a i, const + /// version /// /// @param[in] i /// The breakpoint index to seek for. @@ -138,13 +139,13 @@ public: //------------------------------------------------------------------ /// Removes all invalid breakpoint locations. /// - /// Removes all breakpoint locations in the list with architectures - /// that aren't compatible with \a arch. Also remove any breakpoint - /// locations with whose locations have address where the section - /// has been deleted (module and object files no longer exist). + /// Removes all breakpoint locations in the list with architectures that + /// aren't compatible with \a arch. Also remove any breakpoint locations + /// with whose locations have address where the section has been deleted + /// (module and object files no longer exist). /// - /// This is typically used after the process calls exec, or anytime - /// the architecture of the target changes. + /// This is typically used after the process calls exec, or anytime the + /// architecture of the target changes. /// /// @param[in] arch /// If valid, check the module in each breakpoint to make sure @@ -163,8 +164,8 @@ public: //------------------------------------------------------------------ /// Removes all the breakpoints from this list - first checking the - /// ePermDelete on the breakpoints. This call should be used unless you - /// are shutting down and need to actually clear them all. + /// ePermDelete on the breakpoints. This call should be used unless you are + /// shutting down and need to actually clear them all. //------------------------------------------------------------------ void RemoveAllowed(bool notify); diff --git a/lldb/include/lldb/Breakpoint/BreakpointLocation.h b/lldb/include/lldb/Breakpoint/BreakpointLocation.h index 288d44df990..c5911085e61 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointLocation.h +++ b/lldb/include/lldb/Breakpoint/BreakpointLocation.h @@ -27,22 +27,20 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointLocation BreakpointLocation.h -/// "lldb/Breakpoint/BreakpointLocation.h" -/// @brief Class that manages one unique (by address) instance of a logical -/// breakpoint. +/// "lldb/Breakpoint/BreakpointLocation.h" Class that manages one unique (by +/// address) instance of a logical breakpoint. //---------------------------------------------------------------------- //---------------------------------------------------------------------- /// General Outline: /// A breakpoint location is defined by the breakpoint that produces it, -/// and the address that resulted in this particular instantiation. -/// Each breakpoint location also may have a breakpoint site if its -/// address has been loaded into the program. -/// Finally it has a settable options object. +/// and the address that resulted in this particular instantiation. Each +/// breakpoint location also may have a breakpoint site if its address has +/// been loaded into the program. Finally it has a settable options object. /// /// FIXME: Should we also store some fingerprint for the location, so -/// we can map one location to the "equivalent location" on rerun? This -/// would be useful if you've set options on the locations. +/// we can map one location to the "equivalent location" on rerun? This would +/// be useful if you've set options on the locations. //---------------------------------------------------------------------- class BreakpointLocation @@ -52,22 +50,19 @@ public: ~BreakpointLocation() override; //------------------------------------------------------------------ - /// Gets the load address for this breakpoint location - /// @return + /// Gets the load address for this breakpoint location @return /// Returns breakpoint location load address, \b /// LLDB_INVALID_ADDRESS if not yet set. //------------------------------------------------------------------ lldb::addr_t GetLoadAddress() const override; //------------------------------------------------------------------ - /// Gets the Address for this breakpoint location - /// @return + /// Gets the Address for this breakpoint location @return /// Returns breakpoint location Address. //------------------------------------------------------------------ Address &GetAddress(); //------------------------------------------------------------------ - /// Gets the Breakpoint that created this breakpoint location - /// @return + /// Gets the Breakpoint that created this breakpoint location @return /// Returns the owning breakpoint. //------------------------------------------------------------------ Breakpoint &GetBreakpoint(); @@ -75,12 +70,11 @@ public: Target &GetTarget(); //------------------------------------------------------------------ - /// Determines whether we should stop due to a hit at this - /// breakpoint location. + /// Determines whether we should stop due to a hit at this breakpoint + /// location. /// - /// Side Effects: This may evaluate the breakpoint condition, and - /// run the callback. So this command may do a considerable amount - /// of work. + /// Side Effects: This may evaluate the breakpoint condition, and run the + /// callback. So this command may do a considerable amount of work. /// /// @return /// \b true if this breakpoint location thinks we should stop, @@ -93,8 +87,7 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// If \a enable is \b true, enable the breakpoint, if \b false - /// disable it. + /// If \a enable is \b true, enable the breakpoint, if \b false disable it. //------------------------------------------------------------------ void SetEnabled(bool enabled); @@ -138,8 +131,8 @@ public: //------------------------------------------------------------------ /// Set the callback action invoked when the breakpoint is hit. /// - /// The callback will return a bool indicating whether the target - /// should stop at this breakpoint or not. + /// The callback will return a bool indicating whether the target should + /// stop at this breakpoint or not. /// /// @param[in] callback /// The method that will get called when the breakpoint is hit. @@ -213,8 +206,8 @@ public: bool ResolveBreakpointSite(); //------------------------------------------------------------------ - /// Clear this breakpoint location's breakpoint site - for instance - /// when disabling the breakpoint. + /// Clear this breakpoint location's breakpoint site - for instance when + /// disabling the breakpoint. /// /// @return /// \b true if there was a breakpoint site to be cleared, \b false @@ -223,8 +216,7 @@ public: bool ClearBreakpointSite(); //------------------------------------------------------------------ - /// Return whether this breakpoint location has a breakpoint site. - /// @return + /// Return whether this breakpoint location has a breakpoint site. @return /// \b true if there was a breakpoint site for this breakpoint /// location, \b false otherwise. //------------------------------------------------------------------ @@ -237,8 +229,7 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Print a description of this breakpoint location to the stream - /// \a s. + /// Print a description of this breakpoint location to the stream \a s. /// /// @param[in] s /// The stream to which to print the description. @@ -259,8 +250,8 @@ public: //------------------------------------------------------------------ /// Use this to set location specific breakpoint options. /// - /// It will create a copy of the containing breakpoint's options if - /// that hasn't been done already + /// It will create a copy of the containing breakpoint's options if that + /// hasn't been done already /// /// @return /// A pointer to the breakpoint options. @@ -302,8 +293,7 @@ public: //------------------------------------------------------------------ /// Returns whether we should resolve Indirect functions in setting the - /// breakpoint site - /// for this location. + /// breakpoint site for this location. /// /// @return /// \b true if the breakpoint SITE for this location should be set on the @@ -315,8 +305,7 @@ public: //------------------------------------------------------------------ /// Returns whether the address set in the breakpoint site for this location - /// was found by resolving - /// an indirect symbol. + /// was found by resolving an indirect symbol. /// /// @return /// \b true or \b false as given in the description above. @@ -327,8 +316,7 @@ public: //------------------------------------------------------------------ /// Returns whether the address set in the breakpoint location was re-routed - /// to the target of a - /// re-exported symbol. + /// to the target of a re-exported symbol. /// /// @return /// \b true or \b false as given in the description above. @@ -339,10 +327,8 @@ public: //------------------------------------------------------------------ /// Returns whether the two breakpoint locations might represent "equivalent - /// locations". - /// This is used when modules changed to determine if a Location in the old - /// module might - /// be the "same as" the input location. + /// locations". This is used when modules changed to determine if a Location + /// in the old module might be the "same as" the input location. /// /// @param[in] location /// The location to compare against. diff --git a/lldb/include/lldb/Breakpoint/BreakpointLocationList.h b/lldb/include/lldb/Breakpoint/BreakpointLocationList.h index c05c198f02c..4e61abb2838 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointLocationList.h +++ b/lldb/include/lldb/Breakpoint/BreakpointLocationList.h @@ -26,13 +26,10 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointLocationList BreakpointLocationList.h -/// "lldb/Breakpoint/BreakpointLocationList.h" -/// @brief This class is used by Breakpoint to manage a list of breakpoint -/// locations, -// each breakpoint location in the list -/// has a unique ID, and is unique by Address as well. +/// "lldb/Breakpoint/BreakpointLocationList.h" This class is used by +/// Breakpoint to manage a list of breakpoint locations, each breakpoint +/// location in the list has a unique ID, and is unique by Address as well. //---------------------------------------------------------------------- - class BreakpointLocationList { // Only Breakpoints can make the location list, or add elements to it. This // is not just some random collection of locations. Rather, the act of @@ -50,8 +47,8 @@ public: void Dump(Stream *s) const; //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint location at address - /// \a addr - const version. + /// Returns a shared pointer to the breakpoint location at address \a addr - + /// const version. /// /// @param[in] addr /// The address to look for. @@ -63,8 +60,8 @@ public: const lldb::BreakpointLocationSP FindByAddress(const Address &addr) const; //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint location with id - /// \a breakID, const version. + /// Returns a shared pointer to the breakpoint location with id \a breakID, + /// const version. /// /// @param[in] breakID /// The breakpoint location ID to seek for. @@ -76,8 +73,8 @@ public: lldb::BreakpointLocationSP FindByID(lldb::break_id_t breakID) const; //------------------------------------------------------------------ - /// Returns the breakpoint location id to the breakpoint location - /// at address \a addr. + /// Returns the breakpoint location id to the breakpoint location at address + /// \a addr. /// /// @param[in] addr /// The address to match. @@ -88,9 +85,8 @@ public: lldb::break_id_t FindIDByAddress(const Address &addr); //------------------------------------------------------------------ - /// Returns a breakpoint location list of the breakpoint locations - /// in the module \a module. This list is allocated, and owned by - /// the caller. + /// Returns a breakpoint location list of the breakpoint locations in the + /// module \a module. This list is allocated, and owned by the caller. /// /// @param[in] module /// The module to seek in. @@ -106,8 +102,7 @@ public: BreakpointLocationCollection &bp_loc_list); //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint location with - /// index \a i. + /// Returns a shared pointer to the breakpoint location with index \a i. /// /// @param[in] i /// The breakpoint location index to seek for. @@ -119,8 +114,8 @@ public: lldb::BreakpointLocationSP GetByIndex(size_t i); //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint location with index - /// \a i, const version. + /// Returns a shared pointer to the breakpoint location with index \a i, + /// const version. /// /// @param[in] i /// The breakpoint location index to seek for. @@ -132,20 +127,20 @@ public: const lldb::BreakpointLocationSP GetByIndex(size_t i) const; //------------------------------------------------------------------ - /// Removes all the locations in this list from their breakpoint site - /// owners list. + /// Removes all the locations in this list from their breakpoint site owners + /// list. //------------------------------------------------------------------ void ClearAllBreakpointSites(); //------------------------------------------------------------------ - /// Tells all the breakpoint locations in this list to attempt to - /// resolve any possible breakpoint sites. + /// Tells all the breakpoint locations in this list to attempt to resolve + /// any possible breakpoint sites. //------------------------------------------------------------------ void ResolveAllBreakpointSites(); //------------------------------------------------------------------ - /// Returns the number of breakpoint locations in this list with - /// resolved breakpoints. + /// Returns the number of breakpoint locations in this list with resolved + /// breakpoints. /// /// @result /// Number of qualifying breakpoint locations. @@ -161,8 +156,8 @@ public: uint32_t GetHitCount() const; //------------------------------------------------------------------ - /// Enquires of the breakpoint location in this list with ID \a - /// breakID whether we should stop. + /// Enquires of the breakpoint location in this list with ID \a breakID + /// whether we should stop. /// /// @param[in] context /// This contains the information about this stop. @@ -184,8 +179,8 @@ public: size_t GetSize() const { return m_locations.size(); } //------------------------------------------------------------------ - /// Print a description of the breakpoint locations in this list to - /// the stream \a s. + /// Print a description of the breakpoint locations in this list to the + /// stream \a s. /// /// @param[in] s /// The stream to which to print the description. @@ -202,9 +197,9 @@ protected: //------------------------------------------------------------------ /// This is the standard constructor. /// - /// It creates an empty breakpoint location list. It is protected - /// here because only Breakpoints are allowed to create the - /// breakpoint location list. + /// It creates an empty breakpoint location list. It is protected here + /// because only Breakpoints are allowed to create the breakpoint location + /// list. //------------------------------------------------------------------ BreakpointLocationList(Breakpoint &owner); diff --git a/lldb/include/lldb/Breakpoint/BreakpointOptions.h b/lldb/include/lldb/Breakpoint/BreakpointOptions.h index 385aef3e8c7..84821817f98 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointOptions.h +++ b/lldb/include/lldb/Breakpoint/BreakpointOptions.h @@ -27,9 +27,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointOptions BreakpointOptions.h -/// "lldb/Breakpoint/BreakpointOptions.h" -/// @brief Class that manages the options on a breakpoint or breakpoint -/// location. +/// "lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a +/// breakpoint or breakpoint location. //---------------------------------------------------------------------- class BreakpointOptions { @@ -106,9 +105,8 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// This constructor allows you to specify all the breakpoint options - /// except the callback. That one is more complicated, and better - /// to do by hand. + /// This constructor allows you to specify all the breakpoint options except + /// the callback. That one is more complicated, and better to do by hand. /// /// @param[in] condition /// The expression which if it evaluates to \b true if we are to stop @@ -125,8 +123,8 @@ public: bool auto_continue = false); //------------------------------------------------------------------ - /// Breakpoints make options with all flags set. Locations and Names make options - /// with no flags set. + /// Breakpoints make options with all flags set. Locations and Names make + /// options with no flags set. //------------------------------------------------------------------ BreakpointOptions(bool all_flags_set); BreakpointOptions(const BreakpointOptions &rhs); @@ -363,8 +361,7 @@ public: //------------------------------------------------------------------ /// Return the current thread spec for this option. This will return nullptr - /// if the no thread - /// specifications have been set for this Option yet. + /// if the no thread specifications have been set for this Option yet. /// @return /// The thread specification pointer for this option, or nullptr if none /// has @@ -373,8 +370,8 @@ public: const ThreadSpec *GetThreadSpecNoCreate() const; //------------------------------------------------------------------ - /// Returns a pointer to the ThreadSpec for this option, creating it. - /// if it hasn't been created already. This API is used for setting the + /// Returns a pointer to the ThreadSpec for this option, creating it. if it + /// hasn't been created already. This API is used for setting the /// ThreadSpec items for this option. //------------------------------------------------------------------ ThreadSpec *GetThreadSpec(); @@ -396,8 +393,8 @@ public: lldb::user_id_t break_loc_id); //------------------------------------------------------------------ - /// Set a callback based on BreakpointOptions::CommandData. - /// @param[in] cmd_data + /// Set a callback based on BreakpointOptions::CommandData. @param[in] + /// cmd_data /// A UP holding the new'ed CommandData object. /// The breakpoint will take ownership of pointer held by this object. //------------------------------------------------------------------ diff --git a/lldb/include/lldb/Breakpoint/BreakpointResolver.h b/lldb/include/lldb/Breakpoint/BreakpointResolver.h index 92b74d2b8ea..944741308da 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointResolver.h +++ b/lldb/include/lldb/Breakpoint/BreakpointResolver.h @@ -26,24 +26,19 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointResolver BreakpointResolver.h -/// "lldb/Breakpoint/BreakpointResolver.h" -/// @brief This class works with SearchFilter to resolve logical breakpoints to -/// their -/// of concrete breakpoint locations. +/// "lldb/Breakpoint/BreakpointResolver.h" This class works with SearchFilter +/// to resolve logical breakpoints to their of concrete breakpoint locations. //---------------------------------------------------------------------- //---------------------------------------------------------------------- /// General Outline: -/// The BreakpointResolver is a Searcher. In that protocol, -/// the SearchFilter asks the question "At what depth of the symbol context -/// descent do you want your callback to get called?" of the filter. The -/// resolver -/// answers this question (in the GetDepth method) and provides the resolution -/// callback. +/// The BreakpointResolver is a Searcher. In that protocol, the SearchFilter +/// asks the question "At what depth of the symbol context descent do you want +/// your callback to get called?" of the filter. The resolver answers this +/// question (in the GetDepth method) and provides the resolution callback. /// Each Breakpoint has a BreakpointResolver, and it calls either -/// ResolveBreakpoint -/// or ResolveBreakpointInModules to tell it to look for new breakpoint -/// locations. +/// ResolveBreakpoint or ResolveBreakpointInModules to tell it to look for new +/// breakpoint locations. //---------------------------------------------------------------------- class BreakpointResolver : public Searcher { @@ -53,8 +48,7 @@ public: //------------------------------------------------------------------ /// The breakpoint resolver need to have a breakpoint for "ResolveBreakpoint /// to make sense. It can be constructed without a breakpoint, but you have - /// to - /// call SetBreakpoint before ResolveBreakpoint. + /// to call SetBreakpoint before ResolveBreakpoint. /// /// @param[in] bkpt /// The breakpoint that owns this resolver. @@ -82,9 +76,9 @@ public: void SetBreakpoint(Breakpoint *bkpt); //------------------------------------------------------------------ - /// This updates the offset for this breakpoint. All the locations currently - /// set for this breakpoint will have their offset adjusted when this is - /// called. + /// This updates the offset for this breakpoint. All the locations + /// currently set for this breakpoint will have their offset adjusted when + /// this is called. /// /// @param[in] offset /// The offset to add to all locations. @@ -92,9 +86,9 @@ public: void SetOffset(lldb::addr_t offset); //------------------------------------------------------------------ - /// This updates the offset for this breakpoint. All the locations currently - /// set for this breakpoint will have their offset adjusted when this is - /// called. + /// This updates the offset for this breakpoint. All the locations + /// currently set for this breakpoint will have their offset adjusted when + /// this is called. /// /// @param[in] offset /// The offset to add to all locations. @@ -103,8 +97,7 @@ public: //------------------------------------------------------------------ /// In response to this method the resolver scans all the modules in the - /// breakpoint's - /// target, and adds any new locations it finds. + /// breakpoint's target, and adds any new locations it finds. /// /// @param[in] filter /// The filter that will manage the search for this resolver. @@ -113,8 +106,7 @@ public: //------------------------------------------------------------------ /// In response to this method the resolver scans the modules in the module - /// list - /// \a modules, and adds any new locations it finds. + /// list \a modules, and adds any new locations it finds. /// /// @param[in] filter /// The filter that will manage the search for this resolver. @@ -157,8 +149,8 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// An enumeration for keeping track of the concrete subclass that - /// is actually instantiated. Values of this enumeration are kept in the + /// An enumeration for keeping track of the concrete subclass that is + /// actually instantiated. Values of this enumeration are kept in the /// BreakpointResolver's SubclassID field. They are used for concrete type /// identification. enum ResolverTy { @@ -227,12 +219,10 @@ public: protected: //------------------------------------------------------------------ - /// SetSCMatchesByLine - Takes a symbol context list of matches which - /// supposedly represent the same file and - /// line number in a CU, and find the nearest actual line number that matches, - /// and then filter down the - /// matching addresses to unique entries, and skip the prologue if asked to do - /// so, and then set + /// Takes a symbol context list of matches which supposedly represent the + /// same file and line number in a CU, and find the nearest actual line + /// number that matches, and then filter down the matching addresses to + /// unique entries, and skip the prologue if asked to do so, and then set /// breakpoint locations in this breakpoint for all the resultant addresses. void SetSCMatchesByLine(SearchFilter &filter, SymbolContextList &sc_list, bool skip_prologue, llvm::StringRef log_ident); diff --git a/lldb/include/lldb/Breakpoint/BreakpointResolverAddress.h b/lldb/include/lldb/Breakpoint/BreakpointResolverAddress.h index cc4ab49aae7..5845fe7cabe 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointResolverAddress.h +++ b/lldb/include/lldb/Breakpoint/BreakpointResolverAddress.h @@ -21,10 +21,9 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointResolverAddress BreakpointResolverAddress.h -/// "lldb/Breakpoint/BreakpointResolverAddress.h" -/// @brief This class sets breakpoints on a given Address. This breakpoint only -/// takes -/// once, and then it won't attempt to reset itself. +/// "lldb/Breakpoint/BreakpointResolverAddress.h" This class sets breakpoints +/// on a given Address. This breakpoint only takes once, and then it won't +/// attempt to reset itself. //---------------------------------------------------------------------- class BreakpointResolverAddress : public BreakpointResolver { diff --git a/lldb/include/lldb/Breakpoint/BreakpointResolverFileLine.h b/lldb/include/lldb/Breakpoint/BreakpointResolverFileLine.h index b884560ff99..3464f8ea80d 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointResolverFileLine.h +++ b/lldb/include/lldb/Breakpoint/BreakpointResolverFileLine.h @@ -20,10 +20,9 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointResolverFileLine BreakpointResolverFileLine.h -/// "lldb/Breakpoint/BreakpointResolverFileLine.h" -/// @brief This class sets breakpoints by file and line. Optionally, it will -/// look for inlined -/// instances of the file and line specification. +/// "lldb/Breakpoint/BreakpointResolverFileLine.h" This class sets breakpoints +/// by file and line. Optionally, it will look for inlined instances of the +/// file and line specification. //---------------------------------------------------------------------- class BreakpointResolverFileLine : public BreakpointResolver { diff --git a/lldb/include/lldb/Breakpoint/BreakpointResolverFileRegex.h b/lldb/include/lldb/Breakpoint/BreakpointResolverFileRegex.h index d620e99ffc6..c1a7a15566a 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointResolverFileRegex.h +++ b/lldb/include/lldb/Breakpoint/BreakpointResolverFileRegex.h @@ -23,9 +23,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointResolverFileRegex BreakpointResolverFileRegex.h -/// "lldb/Breakpoint/BreakpointResolverFileRegex.h" -/// @brief This class sets breakpoints by file and line. Optionally, it will -/// look for inlined +/// "lldb/Breakpoint/BreakpointResolverFileRegex.h" This class sets +/// breakpoints by file and line. Optionally, it will look for inlined /// instances of the file and line specification. //---------------------------------------------------------------------- diff --git a/lldb/include/lldb/Breakpoint/BreakpointResolverName.h b/lldb/include/lldb/Breakpoint/BreakpointResolverName.h index fe2c3dd152a..794ea67bb72 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointResolverName.h +++ b/lldb/include/lldb/Breakpoint/BreakpointResolverName.h @@ -24,10 +24,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointResolverName BreakpointResolverName.h -/// "lldb/Breakpoint/BreakpointResolverName.h" -/// @brief This class sets breakpoints on a given function name, either by exact -/// match -/// or by regular expression. +/// "lldb/Breakpoint/BreakpointResolverName.h" This class sets breakpoints on +/// a given function name, either by exact match or by regular expression. //---------------------------------------------------------------------- class BreakpointResolverName : public BreakpointResolver { diff --git a/lldb/include/lldb/Breakpoint/BreakpointSite.h b/lldb/include/lldb/Breakpoint/BreakpointSite.h index 479e4212b4d..c9bd883ca73 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointSite.h +++ b/lldb/include/lldb/Breakpoint/BreakpointSite.h @@ -28,15 +28,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointSite BreakpointSite.h "lldb/Breakpoint/BreakpointSite.h" -/// @brief Class that manages the actual breakpoint that will be inserted -/// into the running program. +/// Class that manages the actual breakpoint that will be inserted into the +/// running program. /// -/// The BreakpointSite class handles the physical breakpoint that is -/// actually inserted in the target program. As such, it is also the -/// one that gets hit, when the program stops. It keeps a list of all -/// BreakpointLocations that share this physical site. When the -/// breakpoint is hit, all the locations are informed by the breakpoint -/// site. Breakpoint sites are owned by the process. +/// The BreakpointSite class handles the physical breakpoint that is actually +/// inserted in the target program. As such, it is also the one that gets +/// hit, when the program stops. It keeps a list of all BreakpointLocations +/// that share this physical site. When the breakpoint is hit, all the +/// locations are informed by the breakpoint site. Breakpoint sites are owned +/// by the process. //---------------------------------------------------------------------- class BreakpointSite : public std::enable_shared_from_this<BreakpointSite>, @@ -101,10 +101,9 @@ public: /// Tells whether the current breakpoint site is enabled or not /// /// This is a low-level enable bit for the breakpoint sites. If a - /// breakpoint site has no enabled owners, it should just get - /// removed. This enable/disable is for the low-level target code - /// to enable and disable breakpoint sites when single stepping, - /// etc. + /// breakpoint site has no enabled owners, it should just get removed. This + /// enable/disable is for the low-level target code to enable and disable + /// breakpoint sites when single stepping, etc. //------------------------------------------------------------------ bool IsEnabled() const; @@ -118,8 +117,7 @@ public: //------------------------------------------------------------------ /// Enquires of the breakpoint locations that produced this breakpoint site - /// whether - /// we should stop at this location. + /// whether we should stop at this location. /// /// @param[in] context /// This contains the information about this stop. @@ -138,9 +136,8 @@ public: void Dump(Stream *s) const override; //------------------------------------------------------------------ - /// The "Owners" are the breakpoint locations that share this - /// breakpoint site. The method adds the \a owner to this breakpoint - /// site's owner list. + /// The "Owners" are the breakpoint locations that share this breakpoint + /// site. The method adds the \a owner to this breakpoint site's owner list. /// /// @param[in] context /// \a owner is the Breakpoint Location to add. @@ -148,8 +145,8 @@ public: void AddOwner(const lldb::BreakpointLocationSP &owner); //------------------------------------------------------------------ - /// This method returns the number of breakpoint locations currently - /// located at this breakpoint site. + /// This method returns the number of breakpoint locations currently located + /// at this breakpoint site. /// /// @return /// The number of owners. @@ -157,10 +154,10 @@ public: size_t GetNumberOfOwners(); //------------------------------------------------------------------ - /// This method returns the breakpoint location at index \a index - /// located at this breakpoint site. The owners are listed ordinally - /// from 0 to GetNumberOfOwners() - 1 so you can use this method to iterate - /// over the owners + /// This method returns the breakpoint location at index \a index located at + /// this breakpoint site. The owners are listed ordinally from 0 to + /// GetNumberOfOwners() - 1 so you can use this method to iterate over the + /// owners /// /// @param[in] index /// The index in the list of owners for which you wish the owner location. @@ -183,9 +180,9 @@ public: size_t CopyOwnersList(BreakpointLocationCollection &out_collection); //------------------------------------------------------------------ - /// Check whether the owners of this breakpoint site have any - /// thread specifiers, and if yes, is \a thread contained in any - /// of these specifiers. + /// Check whether the owners of this breakpoint site have any thread + /// specifiers, and if yes, is \a thread contained in any of these + /// specifiers. /// /// @param[in] thread /// The thread against which to test. @@ -198,9 +195,9 @@ public: //------------------------------------------------------------------ /// Print a description of this breakpoint site to the stream \a s. - /// GetDescription tells you about the breakpoint site's owners. - /// Use BreakpointSite::Dump(Stream *) to get information about the - /// breakpoint site itself. + /// GetDescription tells you about the breakpoint site's owners. Use + /// BreakpointSite::Dump(Stream *) to get information about the breakpoint + /// site itself. /// /// @param[in] s /// The stream to which to print the description. @@ -226,7 +223,8 @@ public: bool IsBreakpointAtThisSite(lldb::break_id_t bp_id); //------------------------------------------------------------------ - /// Tell whether ALL the breakpoints in the location collection are internal. + /// Tell whether ALL the breakpoints in the location collection are + /// internal. /// /// @result /// \b true if all breakpoint locations are owned by internal breakpoints, @@ -249,7 +247,8 @@ private: void BumpHitCounts(); //------------------------------------------------------------------ - /// The method removes the owner at \a break_loc_id from this breakpoint list. + /// The method removes the owner at \a break_loc_id from this breakpoint + /// list. /// /// @param[in] context /// \a break_loc_id is the Breakpoint Location to remove. diff --git a/lldb/include/lldb/Breakpoint/BreakpointSiteList.h b/lldb/include/lldb/Breakpoint/BreakpointSiteList.h index 1431fe79967..d6530c17043 100644 --- a/lldb/include/lldb/Breakpoint/BreakpointSiteList.h +++ b/lldb/include/lldb/Breakpoint/BreakpointSiteList.h @@ -24,8 +24,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class BreakpointSiteList BreakpointSiteList.h -/// "lldb/Breakpoint/BreakpointSiteList.h" -/// @brief Class that manages lists of BreakpointSite shared pointers. +/// "lldb/Breakpoint/BreakpointSiteList.h" Class that manages lists of +/// BreakpointSite shared pointers. //---------------------------------------------------------------------- class BreakpointSiteList { // At present Process directly accesses the map of BreakpointSites so it can @@ -56,15 +56,13 @@ public: lldb::break_id_t Add(const lldb::BreakpointSiteSP &bp_site_sp); //------------------------------------------------------------------ - /// Standard Dump routine, doesn't do anything at present. - /// @param[in] s + /// Standard Dump routine, doesn't do anything at present. @param[in] s /// Stream into which to dump the description. //------------------------------------------------------------------ void Dump(Stream *s) const; //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint site at address - /// \a addr. + /// Returns a shared pointer to the breakpoint site at address \a addr. /// /// @param[in] addr /// The address to look for. @@ -89,8 +87,8 @@ public: lldb::BreakpointSiteSP FindByID(lldb::break_id_t breakID); //------------------------------------------------------------------ - /// Returns a shared pointer to the breakpoint site with id \a breakID - const - /// version. + /// Returns a shared pointer to the breakpoint site with id \a breakID - + /// const version. /// /// @param[in] breakID /// The breakpoint site ID to seek for. @@ -103,7 +101,8 @@ public: const lldb::BreakpointSiteSP FindByID(lldb::break_id_t breakID) const; //------------------------------------------------------------------ - /// Returns the breakpoint site id to the breakpoint site at address \a addr. + /// Returns the breakpoint site id to the breakpoint site at address \a + /// addr. /// /// @param[in] addr /// The address to match. @@ -161,8 +160,8 @@ public: void *baton); //------------------------------------------------------------------ - /// Enquires of the breakpoint site on in this list with ID \a breakID whether - /// we should stop for the breakpoint or not. + /// Enquires of the breakpoint site on in this list with ID \a breakID + /// whether we should stop for the breakpoint or not. /// /// @param[in] context /// This contains the information about this stop. diff --git a/lldb/include/lldb/Breakpoint/StoppointCallbackContext.h b/lldb/include/lldb/Breakpoint/StoppointCallbackContext.h index 2680584845d..1dac342d332 100644 --- a/lldb/include/lldb/Breakpoint/StoppointCallbackContext.h +++ b/lldb/include/lldb/Breakpoint/StoppointCallbackContext.h @@ -17,18 +17,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class StoppointCallbackContext StoppointCallbackContext.h -/// "lldb/Breakpoint/StoppointCallbackContext.h" -/// @brief Class holds the information that a breakpoint callback needs to -/// evaluate this stop. +/// "lldb/Breakpoint/StoppointCallbackContext.h" Class holds the information +/// that a breakpoint callback needs to evaluate this stop. //---------------------------------------------------------------------- //---------------------------------------------------------------------- /// General Outline: /// When we hit a breakpoint we need to package up whatever information is -/// needed -/// to evaluate breakpoint commands and conditions. This class is the container -/// of -/// that information. +/// needed to evaluate breakpoint commands and conditions. This class is the +/// container of that information. //---------------------------------------------------------------------- class StoppointCallbackContext { diff --git a/lldb/include/lldb/Breakpoint/WatchpointList.h b/lldb/include/lldb/Breakpoint/WatchpointList.h index ffb8df8d9eb..d5e0da444af 100644 --- a/lldb/include/lldb/Breakpoint/WatchpointList.h +++ b/lldb/include/lldb/Breakpoint/WatchpointList.h @@ -25,7 +25,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class WatchpointList WatchpointList.h "lldb/Breakpoint/WatchpointList.h" -/// @brief This class is used by Watchpoint to manage a list of watchpoints, +/// This class is used by Watchpoint to manage a list of watchpoints, // each watchpoint in the list has a unique ID, and is unique by Address as // well. //---------------------------------------------------------------------- @@ -70,9 +70,8 @@ public: void DumpWithLevel(Stream *s, lldb::DescriptionLevel description_level) const; //------------------------------------------------------------------ - /// Returns a shared pointer to the watchpoint at address - /// \a addr - - /// const version. + /// Returns a shared pointer to the watchpoint at address \a addr - const + /// version. /// /// @param[in] addr /// The address to look for. @@ -84,9 +83,8 @@ public: const lldb::WatchpointSP FindByAddress(lldb::addr_t addr) const; //------------------------------------------------------------------ - /// Returns a shared pointer to the watchpoint with watchpoint spec - /// \a spec - - /// const version. + /// Returns a shared pointer to the watchpoint with watchpoint spec \a spec + /// - const version. /// /// @param[in] spec /// The watchpoint spec to look for. @@ -98,8 +96,7 @@ public: const lldb::WatchpointSP FindBySpec(std::string spec) const; //------------------------------------------------------------------ - /// Returns a shared pointer to the watchpoint with id - /// \a watchID, const + /// Returns a shared pointer to the watchpoint with id \a watchID, const /// version. /// /// @param[in] watchID @@ -112,8 +109,7 @@ public: lldb::WatchpointSP FindByID(lldb::watch_id_t watchID) const; //------------------------------------------------------------------ - /// Returns the watchpoint id to the watchpoint - /// at address \a addr. + /// Returns the watchpoint id to the watchpoint at address \a addr. /// /// @param[in] addr /// The address to match. @@ -124,8 +120,8 @@ public: lldb::watch_id_t FindIDByAddress(lldb::addr_t addr); //------------------------------------------------------------------ - /// Returns the watchpoint id to the watchpoint - /// with watchpoint spec \a spec. + /// Returns the watchpoint id to the watchpoint with watchpoint spec \a + /// spec. /// /// @param[in] spec /// The watchpoint spec to match. diff --git a/lldb/include/lldb/Breakpoint/WatchpointOptions.h b/lldb/include/lldb/Breakpoint/WatchpointOptions.h index 8e71e304554..8cb3b97f3a6 100644 --- a/lldb/include/lldb/Breakpoint/WatchpointOptions.h +++ b/lldb/include/lldb/Breakpoint/WatchpointOptions.h @@ -25,8 +25,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class WatchpointOptions WatchpointOptions.h -/// "lldb/Breakpoint/WatchpointOptions.h" -/// @brief Class that manages the options on a watchpoint. +/// "lldb/Breakpoint/WatchpointOptions.h" Class that manages the options on a +/// watchpoint. //---------------------------------------------------------------------- class WatchpointOptions { @@ -166,8 +166,7 @@ public: //------------------------------------------------------------------ /// Return the current thread spec for this option. This will return nullptr - /// if the no thread - /// specifications have been set for this Option yet. + /// if the no thread specifications have been set for this Option yet. /// @return /// The thread specification pointer for this option, or nullptr if none /// has @@ -176,8 +175,8 @@ public: const ThreadSpec *GetThreadSpecNoCreate() const; //------------------------------------------------------------------ - /// Returns a pointer to the ThreadSpec for this option, creating it. - /// if it hasn't been created already. This API is used for setting the + /// Returns a pointer to the ThreadSpec for this option, creating it. if it + /// hasn't been created already. This API is used for setting the /// ThreadSpec items for this option. //------------------------------------------------------------------ ThreadSpec *GetThreadSpec(); diff --git a/lldb/include/lldb/Core/Address.h b/lldb/include/lldb/Core/Address.h index f672524416f..e892ce4e96e 100644 --- a/lldb/include/lldb/Core/Address.h +++ b/lldb/include/lldb/Core/Address.h @@ -53,54 +53,50 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Address Address.h "lldb/Core/Address.h" -/// @brief A section + offset based address class. +/// A section + offset based address class. /// -/// The Address class allows addresses to be relative to a section -/// that can move during runtime due to images (executables, shared -/// libraries, bundles, frameworks) being loaded at different -/// addresses than the addresses found in the object file that -/// represents them on disk. There are currently two types of addresses -/// for a section: +/// The Address class allows addresses to be relative to a section that can +/// move during runtime due to images (executables, shared libraries, bundles, +/// frameworks) being loaded at different addresses than the addresses found +/// in the object file that represents them on disk. There are currently two +/// types of addresses for a section: /// @li file addresses /// @li load addresses /// -/// File addresses represent the virtual addresses that are in the "on -/// disk" object files. These virtual addresses are converted to be -/// relative to unique sections scoped to the object file so that -/// when/if the addresses slide when the images are loaded/unloaded -/// in memory, we can easily track these changes without having to -/// update every object (compile unit ranges, line tables, function -/// address ranges, lexical block and inlined subroutine address -/// ranges, global and static variables) each time an image is loaded or -/// unloaded. +/// File addresses represent the virtual addresses that are in the "on disk" +/// object files. These virtual addresses are converted to be relative to +/// unique sections scoped to the object file so that when/if the addresses +/// slide when the images are loaded/unloaded in memory, we can easily track +/// these changes without having to update every object (compile unit ranges, +/// line tables, function address ranges, lexical block and inlined subroutine +/// address ranges, global and static variables) each time an image is loaded +/// or unloaded. /// -/// Load addresses represent the virtual addresses where each section -/// ends up getting loaded at runtime. Before executing a program, it -/// is common for all of the load addresses to be unresolved. When a -/// DynamicLoader plug-in receives notification that shared libraries -/// have been loaded/unloaded, the load addresses of the main executable -/// and any images (shared libraries) will be resolved/unresolved. When -/// this happens, breakpoints that are in one of these sections can be -/// set/cleared. +/// Load addresses represent the virtual addresses where each section ends up +/// getting loaded at runtime. Before executing a program, it is common for +/// all of the load addresses to be unresolved. When a DynamicLoader plug-in +/// receives notification that shared libraries have been loaded/unloaded, the +/// load addresses of the main executable and any images (shared libraries) +/// will be resolved/unresolved. When this happens, breakpoints that are in +/// one of these sections can be set/cleared. //---------------------------------------------------------------------- class Address { public: //------------------------------------------------------------------ - /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const - /// function to display Address contents in a variety of ways. + /// Dump styles allow the Address::Dump(Stream *,DumpStyle) const function + /// to display Address contents in a variety of ways. //------------------------------------------------------------------ typedef enum { DumpStyleInvalid, ///< Invalid dump style DumpStyleSectionNameOffset, ///< Display as the section name + offset. ///< \code /// // address for printf in libSystem.B.dylib as a section name + offset - /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf - /// \endcode + /// libSystem.B.dylib.__TEXT.__text + 0x0005cfdf \endcode DumpStyleSectionPointerOffset, ///< Display as the section pointer + offset ///(debug output). ///< \code - /// // address for printf in libSystem.B.dylib as a section pointer + offset - /// (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode + /// // address for printf in libSystem.B.dylib as a section pointer + + /// offset (lldb::Section *)0x35cc50 + 0x000000000005cfdf \endcode DumpStyleFileAddress, ///< Display as the file address (if any). ///< \code /// // address for printf in libSystem.B.dylib as a file address @@ -135,8 +131,8 @@ public: //------------------------------------------------------------------ /// Default constructor. /// - /// Initialize with a invalid section (NULL) and an invalid - /// offset (LLDB_INVALID_ADDRESS). + /// Initialize with a invalid section (NULL) and an invalid offset + /// (LLDB_INVALID_ADDRESS). //------------------------------------------------------------------ Address() : m_section_wp(), m_offset(LLDB_INVALID_ADDRESS) {} @@ -154,8 +150,7 @@ public: //------------------------------------------------------------------ /// Construct with a section pointer and offset. /// - /// Initialize the address with the supplied \a section and \a - /// offset. + /// Initialize the address with the supplied \a section and \a offset. /// /// @param[in] section /// A section pointer to a valid lldb::Section, or NULL if the @@ -175,8 +170,8 @@ public: //------------------------------------------------------------------ /// Construct with a virtual address and section list. /// - /// Initialize and resolve the address with the supplied virtual - /// address \a file_addr. + /// Initialize and resolve the address with the supplied virtual address \a + /// file_addr. /// /// @param[in] file_addr /// A virtual file address. @@ -191,8 +186,8 @@ public: //------------------------------------------------------------------ /// Assignment operator. /// -/// Copies the address value from another Address object \a rhs -/// into \a this object. +/// Copies the address value from another Address object \a rhs into \a this +/// object. /// /// @param[in] rhs /// A const Address object reference to copy. @@ -207,8 +202,8 @@ public: //------------------------------------------------------------------ /// Clear the object's state. /// - /// Sets the section to an invalid value (NULL) and an invalid - /// offset (LLDB_INVALID_ADDRESS). + /// Sets the section to an invalid value (NULL) and an invalid offset + /// (LLDB_INVALID_ADDRESS). //------------------------------------------------------------------ void Clear() { m_section_wp.reset(); @@ -250,9 +245,9 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. There are many ways to display a section - /// offset based address, and \a style lets the user choose. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. There are many ways to display a section offset based address, and + /// \a style lets the user choose. /// /// @param[in] s /// The stream to which to dump the object description. @@ -280,9 +275,9 @@ public: //------------------------------------------------------------------ /// Get the file address. /// - /// If an address comes from a file on disk that has section - /// relative addresses, then it has a virtual address that is - /// relative to unique section in the object file. + /// If an address comes from a file on disk that has section relative + /// addresses, then it has a virtual address that is relative to unique + /// section in the object file. /// /// @return /// The valid file virtual address, or LLDB_INVALID_ADDRESS if @@ -294,12 +289,12 @@ public: //------------------------------------------------------------------ /// Get the load address. /// - /// If an address comes from a file on disk that has section - /// relative addresses, then it has a virtual address that is - /// relative to unique section in the object file. Sections get - /// resolved at runtime by DynamicLoader plug-ins as images - /// (executables and shared libraries) get loaded/unloaded. If a - /// section is loaded, then the load address can be resolved. + /// If an address comes from a file on disk that has section relative + /// addresses, then it has a virtual address that is relative to unique + /// section in the object file. Sections get resolved at runtime by + /// DynamicLoader plug-ins as images (executables and shared libraries) get + /// loaded/unloaded. If a section is loaded, then the load address can be + /// resolved. /// /// @return /// The valid load virtual address, or LLDB_INVALID_ADDRESS if @@ -310,12 +305,12 @@ public: //------------------------------------------------------------------ /// Get the load address as a callable code load address. /// - /// This function will first resolve its address to a load address. - /// Then, if the address turns out to be in code address, return the - /// load address that would be required to call or return to. The - /// address might have extra bits set (bit zero will be set to Thumb - /// functions for an ARM target) that are required when changing the - /// program counter to setting a return address. + /// This function will first resolve its address to a load address. Then, if + /// the address turns out to be in code address, return the load address + /// that would be required to call or return to. The address might have + /// extra bits set (bit zero will be set to Thumb functions for an ARM + /// target) that are required when changing the program counter to setting a + /// return address. /// /// @return /// The valid load virtual address, or LLDB_INVALID_ADDRESS if @@ -327,14 +322,14 @@ public: //------------------------------------------------------------------ /// Get the load address as an opcode load address. /// - /// This function will first resolve its address to a load address. - /// Then, if the address turns out to be in code address, return the - /// load address for an opcode. This address object might have - /// extra bits set (bit zero will be set to Thumb functions for an + /// This function will first resolve its address to a load address. Then, if + /// the address turns out to be in code address, return the load address for + /// an opcode. This address object might have extra bits set (bit zero will + /// be set to Thumb functions for an /// ARM target) that are required for changing the program counter - /// and this function will remove any bits that are intended for - /// these special purposes. The result of this function can be used - /// to safely write a software breakpoint trap to memory. + /// and this function will remove any bits that are intended for these + /// special purposes. The result of this function can be used to safely + /// write a software breakpoint trap to memory. /// /// @return /// The valid load virtual address with extra callable bits @@ -357,11 +352,11 @@ public: //------------------------------------------------------------------ /// Check if an address is section offset. /// - /// When converting a virtual file or load address into a section - /// offset based address, we often need to know if, given a section - /// list, if the address was able to be converted to section offset. - /// This function returns true if the current value contained in - /// this object is section offset based. + /// When converting a virtual file or load address into a section offset + /// based address, we often need to know if, given a section list, if the + /// address was able to be converted to section offset. This function + /// returns true if the current value contained in this object is section + /// offset based. /// /// @return /// Returns \b true if the address has a valid section and @@ -375,8 +370,8 @@ public: /// Check if the object state is valid. /// /// A valid Address object contains either a section pointer and - /// and offset (for section offset based addresses), or just a valid - /// offset (for absolute addresses that have no section). + /// and offset (for section offset based addresses), or just a valid offset + /// (for absolute addresses that have no section). /// /// @return /// Returns \b true if the offset is valid, \b false @@ -395,8 +390,8 @@ public: //------------------------------------------------------------------ /// Resolve a file virtual address using a section list. /// - /// Given a list of sections, attempt to resolve \a addr as a - /// an offset into one of the file sections. + /// Given a list of sections, attempt to resolve \a addr as a an offset into + /// one of the file sections. /// /// @return /// Returns \b true if \a addr was able to be resolved, \b false @@ -408,11 +403,10 @@ public: //------------------------------------------------------------------ /// Set the address to represent \a load_addr. /// - /// The address will attempt to find a loaded section within - /// \a target that contains \a load_addr. If successful, this - /// address object will have a valid section and offset. Else this - /// address object will have no section (NULL) and the offset will - /// be \a load_addr. + /// The address will attempt to find a loaded section within \a target that + /// contains \a load_addr. If successful, this address object will have a + /// valid section and offset. Else this address object will have no section + /// (NULL) and the offset will be \a load_addr. /// /// @param[in] load_addr /// A load address from a current process. @@ -507,10 +501,10 @@ public: //------------------------------------------------------------------ /// Reconstruct a symbol context from an address. /// - /// This class doesn't inherit from SymbolContextScope because many - /// address objects have short lifespans. Address objects that are - /// section offset can reconstruct their symbol context by looking - /// up the address in the module found in the section. + /// This class doesn't inherit from SymbolContextScope because many address + /// objects have short lifespans. Address objects that are section offset + /// can reconstruct their symbol context by looking up the address in the + /// module found in the section. /// /// @see SymbolContextScope::CalculateSymbolContext(SymbolContext*) //------------------------------------------------------------------ diff --git a/lldb/include/lldb/Core/AddressRange.h b/lldb/include/lldb/Core/AddressRange.h index 5198278fa4e..9f69c87ee35 100644 --- a/lldb/include/lldb/Core/AddressRange.h +++ b/lldb/include/lldb/Core/AddressRange.h @@ -30,23 +30,23 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class AddressRange AddressRange.h "lldb/Core/AddressRange.h" -/// @brief A section + offset based address range class. +/// A section + offset based address range class. //---------------------------------------------------------------------- class AddressRange { public: //------------------------------------------------------------------ /// Default constructor. /// - /// Initialize with a invalid section (NULL), an invalid - /// offset (LLDB_INVALID_ADDRESS), and zero byte size. + /// Initialize with a invalid section (NULL), an invalid offset + /// (LLDB_INVALID_ADDRESS), and zero byte size. //------------------------------------------------------------------ AddressRange(); //------------------------------------------------------------------ /// Construct with a section pointer, offset, and byte_size. /// - /// Initialize the address with the supplied \a section, \a - /// offset and \a byte_size. + /// Initialize the address with the supplied \a section, \a offset and \a + /// byte_size. /// /// @param[in] section /// A section pointer to a valid lldb::Section, or NULL if the @@ -64,8 +64,8 @@ public: //------------------------------------------------------------------ /// Construct with a virtual address, section list and byte size. /// - /// Initialize and resolve the address with the supplied virtual - /// address \a file_addr, and byte size \a byte_size. + /// Initialize and resolve the address with the supplied virtual address \a + /// file_addr, and byte size \a byte_size. /// /// @param[in] file_addr /// A virtual address. @@ -82,8 +82,8 @@ public: //------------------------------------------------------------------ /// Construct with a Address object address and byte size. /// - /// Initialize by copying the section offset address in \a so_addr, - /// and setting the byte size to \a byte_size. + /// Initialize by copying the section offset address in \a so_addr, and + /// setting the byte size to \a byte_size. /// /// @param[in] so_addr /// A section offset address object. @@ -135,8 +135,8 @@ public: // Contains (const Address *so_addr_ptr) const; //------------------------------------------------------------------ - /// Check if a section offset \a so_addr when represented as a file - /// address is contained within this object's file address range. + /// Check if a section offset \a so_addr when represented as a file address + /// is contained within this object's file address range. /// /// @param[in] so_addr /// A section offset address object reference. @@ -149,8 +149,8 @@ public: bool ContainsFileAddress(const Address &so_addr) const; //------------------------------------------------------------------ - /// Check if the resolved file address \a file_addr is contained - /// within this object's file address range. + /// Check if the resolved file address \a file_addr is contained within this + /// object's file address range. /// /// @param[in] so_addr /// A section offset address object reference. @@ -163,8 +163,8 @@ public: bool ContainsFileAddress(lldb::addr_t file_addr) const; //------------------------------------------------------------------ - /// Check if a section offset \a so_addr when represented as a load - /// address is contained within this object's load address range. + /// Check if a section offset \a so_addr when represented as a load address + /// is contained within this object's load address range. /// /// @param[in] so_addr /// A section offset address object reference. @@ -177,8 +177,8 @@ public: bool ContainsLoadAddress(const Address &so_addr, Target *target) const; //------------------------------------------------------------------ - /// Check if the resolved load address \a load_addr is contained - /// within this object's load address range. + /// Check if the resolved load address \a load_addr is contained within this + /// object's load address range. /// /// @param[in] so_addr /// A section offset address object reference. @@ -193,10 +193,10 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. There are many ways to display a section - /// offset based address range, and \a style lets the user choose - /// how the base address gets displayed. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. There are many ways to display a section offset based address + /// range, and \a style lets the user choose how the base address gets + /// displayed. /// /// @param[in] s /// The stream to which to dump the object description. @@ -219,11 +219,11 @@ public: //------------------------------------------------------------------ /// Dump a debug description of this object to a Stream. /// - /// Dump a debug description of the contents of this object to the - /// supplied stream \a s. + /// Dump a debug description of the contents of this object to the supplied + /// stream \a s. /// - /// The debug description contains verbose internal state such - /// and pointer values, reference counts, etc. + /// The debug description contains verbose internal state such and pointer + /// values, reference counts, etc. /// /// @param[in] s /// The stream to which to dump the object description. diff --git a/lldb/include/lldb/Core/AddressResolver.h b/lldb/include/lldb/Core/AddressResolver.h index 432268e497b..cfd103e0be0 100644 --- a/lldb/include/lldb/Core/AddressResolver.h +++ b/lldb/include/lldb/Core/AddressResolver.h @@ -27,18 +27,16 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class AddressResolver AddressResolver.h "lldb/Core/AddressResolver.h" -/// @brief This class works with SearchFilter to resolve function names and -/// source file locations to their concrete addresses. +/// This class works with SearchFilter to resolve function names and source +/// file locations to their concrete addresses. //---------------------------------------------------------------------- //---------------------------------------------------------------------- /// General Outline: -/// The AddressResolver is a Searcher. In that protocol, -/// the SearchFilter asks the question "At what depth of the symbol context -/// descent do you want your callback to get called?" of the filter. The -/// resolver -/// answers this question (in the GetDepth method) and provides the resolution -/// callback. +/// The AddressResolver is a Searcher. In that protocol, the SearchFilter +/// asks the question "At what depth of the symbol context descent do you want +/// your callback to get called?" of the filter. The resolver answers this +/// question (in the GetDepth method) and provides the resolution callback. //---------------------------------------------------------------------- class AddressResolver : public Searcher { diff --git a/lldb/include/lldb/Core/AddressResolverFileLine.h b/lldb/include/lldb/Core/AddressResolverFileLine.h index ec15cc76d88..e434a62e031 100644 --- a/lldb/include/lldb/Core/AddressResolverFileLine.h +++ b/lldb/include/lldb/Core/AddressResolverFileLine.h @@ -31,10 +31,9 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class AddressResolverFileLine AddressResolverFileLine.h -/// "lldb/Core/AddressResolverFileLine.h" -/// @brief This class finds address for source file and line. Optionally, it -/// will look for inlined -/// instances of the file and line specification. +/// "lldb/Core/AddressResolverFileLine.h" This class finds address for source +/// file and line. Optionally, it will look for inlined instances of the file +/// and line specification. //---------------------------------------------------------------------- class AddressResolverFileLine : public AddressResolver { diff --git a/lldb/include/lldb/Core/AddressResolverName.h b/lldb/include/lldb/Core/AddressResolverName.h index 616fbeba861..49a805f2115 100644 --- a/lldb/include/lldb/Core/AddressResolverName.h +++ b/lldb/include/lldb/Core/AddressResolverName.h @@ -30,10 +30,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class AddressResolverName AddressResolverName.h -/// "lldb/Core/AddressResolverName.h" -/// @brief This class finds addresses for a given function name, either by exact -/// match -/// or by regular expression. +/// "lldb/Core/AddressResolverName.h" This class finds addresses for a given +/// function name, either by exact match or by regular expression. //---------------------------------------------------------------------- class AddressResolverName : public AddressResolver { diff --git a/lldb/include/lldb/Core/Broadcaster.h b/lldb/include/lldb/Core/Broadcaster.h index 90bd62c2d82..b9d4e5ca17a 100644 --- a/lldb/include/lldb/Core/Broadcaster.h +++ b/lldb/include/lldb/Core/Broadcaster.h @@ -223,21 +223,21 @@ private: }; //---------------------------------------------------------------------- -/// @class Broadcaster Broadcaster.h "lldb/Core/Broadcaster.h" -/// @brief An event broadcasting class. +/// @class Broadcaster Broadcaster.h "lldb/Core/Broadcaster.h" An event +/// broadcasting class. /// -/// The Broadcaster class is designed to be subclassed by objects that -/// wish to vend events in a multi-threaded environment. Broadcaster -/// objects can each vend 32 events. Each event is represented by a bit -/// in a 32 bit value and these bits can be set: +/// The Broadcaster class is designed to be subclassed by objects that wish to +/// vend events in a multi-threaded environment. Broadcaster objects can each +/// vend 32 events. Each event is represented by a bit in a 32 bit value and +/// these bits can be set: /// @see Broadcaster::SetEventBits(uint32_t) /// or cleared: /// @see Broadcaster::ResetEventBits(uint32_t) -/// When an event gets set the Broadcaster object will notify the -/// Listener object that is listening for the event (if there is one). +/// When an event gets set the Broadcaster object will notify the Listener +/// object that is listening for the event (if there is one). /// -/// Subclasses should provide broadcast bit definitions for any events -/// they vend, typically using an enumeration: +/// Subclasses should provide broadcast bit definitions for any events they +/// vend, typically using an enumeration: /// \code /// class Foo : public Broadcaster /// { @@ -323,12 +323,11 @@ public: //------------------------------------------------------------------ /// Listen for any events specified by \a event_mask. /// - /// Only one listener can listen to each event bit in a given - /// Broadcaster. Once a listener has acquired an event bit, no - /// other broadcaster will have access to it until it is - /// relinquished by the first listener that gets it. The actual - /// event bits that get acquired by \a listener may be different - /// from what is requested in \a event_mask, and to track this the + /// Only one listener can listen to each event bit in a given Broadcaster. + /// Once a listener has acquired an event bit, no other broadcaster will + /// have access to it until it is relinquished by the first listener that + /// gets it. The actual event bits that get acquired by \a listener may be + /// different from what is requested in \a event_mask, and to track this the /// actual event bits that are acquired get returned. /// /// @param[in] listener @@ -348,8 +347,7 @@ public: } //------------------------------------------------------------------ - /// Get the NULL terminated C string name of this Broadcaster - /// object. + /// Get the NULL terminated C string name of this Broadcaster object. /// /// @return /// The NULL terminated C string name of this Broadcaster. @@ -394,10 +392,10 @@ public: } //------------------------------------------------------------------ - /// Removes a Listener from this broadcasters list and frees the - /// event bits specified by \a event_mask that were previously - /// acquired by \a listener (assuming \a listener was listening to - /// this object) for other listener objects to use. + /// Removes a Listener from this broadcasters list and frees the event bits + /// specified by \a event_mask that were previously acquired by \a listener + /// (assuming \a listener was listening to this object) for other listener + /// objects to use. /// /// @param[in] listener /// A Listener object that previously called AddListener. @@ -419,10 +417,9 @@ public: //------------------------------------------------------------------ /// Provides a simple mechanism to temporarily redirect events from /// broadcaster. When you call this function passing in a listener and - /// event type mask, all events from the broadcaster matching the mask - /// will now go to the hijacking listener. - /// Only one hijack can occur at a time. If we need more than this we - /// will have to implement a Listener stack. + /// event type mask, all events from the broadcaster matching the mask will + /// now go to the hijacking listener. Only one hijack can occur at a time. + /// If we need more than this we will have to implement a Listener stack. /// /// @param[in] listener /// A Listener object. You do not need to call StartListeningForEvents diff --git a/lldb/include/lldb/Core/Communication.h b/lldb/include/lldb/Core/Communication.h index 57fa483bd3a..3e29307039e 100644 --- a/lldb/include/lldb/Core/Communication.h +++ b/lldb/include/lldb/Core/Communication.h @@ -39,60 +39,57 @@ class Status; namespace lldb_private { //---------------------------------------------------------------------- -/// @class Communication Communication.h "lldb/Core/Communication.h" -/// @brief An abstract communications class. +/// @class Communication Communication.h "lldb/Core/Communication.h" An +/// abstract communications class. /// -/// Communication is an class that handles data communication -/// between two data sources. It uses a Connection class to do the -/// real communication. This approach has a couple of advantages: it -/// allows a single instance of this class to be used even though its -/// connection can change. Connections could negotiate for different -/// connections based on abilities like starting with Bluetooth and -/// negotiating up to WiFi if available. It also allows this class to be -/// subclassed by any interfaces that don't want to give bytes but want -/// to validate and give out packets. This can be done by overriding: +/// Communication is an class that handles data communication between two data +/// sources. It uses a Connection class to do the real communication. This +/// approach has a couple of advantages: it allows a single instance of this +/// class to be used even though its connection can change. Connections could +/// negotiate for different connections based on abilities like starting with +/// Bluetooth and negotiating up to WiFi if available. It also allows this +/// class to be subclassed by any interfaces that don't want to give bytes but +/// want to validate and give out packets. This can be done by overriding: /// /// AppendBytesToCache (const uint8_t *src, size_t src_len, bool broadcast); /// -/// Communication inherits from Broadcaster which means it can be -/// used in conjunction with Listener to wait for multiple broadcaster -/// objects and multiple events from each of those objects. -/// Communication defines a set of pre-defined event bits (see -/// enumerations definitions that start with "eBroadcastBit" below). +/// Communication inherits from Broadcaster which means it can be used in +/// conjunction with Listener to wait for multiple broadcaster objects and +/// multiple events from each of those objects. Communication defines a set of +/// pre-defined event bits (see enumerations definitions that start with +/// "eBroadcastBit" below). /// /// There are two modes in which communications can occur: /// @li single-threaded /// @li multi-threaded /// -/// In single-threaded mode, all reads and writes happen synchronously -/// on the calling thread. +/// In single-threaded mode, all reads and writes happen synchronously on the +/// calling thread. /// -/// In multi-threaded mode, a read thread is spawned that continually -/// reads data and caches any received bytes. To start the read thread -/// clients call: +/// In multi-threaded mode, a read thread is spawned that continually reads +/// data and caches any received bytes. To start the read thread clients call: /// /// bool Communication::StartReadThread (Status *); /// -/// If true is returned a read thread has been spawned that will -/// continually execute a call to the pure virtual DoRead function: +/// If true is returned a read thread has been spawned that will continually +/// execute a call to the pure virtual DoRead function: /// /// size_t Communication::ReadFromConnection (void *, size_t, uint32_t); /// -/// When bytes are received the data gets cached in \a m_bytes and this -/// class will broadcast a \b eBroadcastBitReadThreadGotBytes event. -/// Clients that want packet based communication should override -/// AppendBytesToCache. The subclasses can choose to call the -/// built in AppendBytesToCache with the \a broadcast parameter set to -/// false. This will cause the \b eBroadcastBitReadThreadGotBytes event -/// not get broadcast, and then the subclass can post a \b -/// eBroadcastBitPacketAvailable event when a full packet of data has -/// been received. +/// When bytes are received the data gets cached in \a m_bytes and this class +/// will broadcast a \b eBroadcastBitReadThreadGotBytes event. Clients that +/// want packet based communication should override AppendBytesToCache. The +/// subclasses can choose to call the built in AppendBytesToCache with the \a +/// broadcast parameter set to false. This will cause the \b +/// eBroadcastBitReadThreadGotBytes event not get broadcast, and then the +/// subclass can post a \b eBroadcastBitPacketAvailable event when a full +/// packet of data has been received. /// -/// If the connection is disconnected a \b eBroadcastBitDisconnected -/// event gets broadcast. If the read thread exits a \b -/// eBroadcastBitReadThreadDidExit event will be broadcast. Clients -/// can also post a \b eBroadcastBitReadThreadShouldExit event to this -/// object which will cause the read thread to exit. +/// If the connection is disconnected a \b eBroadcastBitDisconnected event +/// gets broadcast. If the read thread exits a \b +/// eBroadcastBitReadThreadDidExit event will be broadcast. Clients can also +/// post a \b eBroadcastBitReadThreadShouldExit event to this object which +/// will cause the read thread to exit. //---------------------------------------------------------------------- class Communication : public Broadcaster { public: @@ -120,8 +117,8 @@ public: size_t src_len); //------------------------------------------------------------------ - /// Construct the Communication object with the specified name for - /// the Broadcaster that this object inherits from. + /// Construct the Communication object with the specified name for the + /// Broadcaster that this object inherits from. /// /// @param[in] broadcaster_name /// The name of the broadcaster object. This name should be as @@ -141,9 +138,8 @@ public: void Clear(); //------------------------------------------------------------------ - /// Connect using the current connection by passing \a url to its - /// connect function. - /// string. + /// Connect using the current connection by passing \a url to its connect + /// function. string. /// /// @param[in] url /// A string that contains all information needed by the @@ -160,8 +156,7 @@ public: lldb::ConnectionStatus Connect(const char *url, Status *error_ptr); //------------------------------------------------------------------ - /// Disconnect the communications connection if one is currently - /// connected. + /// Disconnect the communications connection if one is currently connected. /// /// @return /// \b True if the disconnect succeeded, \b false otherwise. The @@ -189,16 +184,15 @@ public: //------------------------------------------------------------------ /// Read bytes from the current connection. /// - /// If no read thread is running, this function call the - /// connection's Connection::Read(...) function to get any available. + /// If no read thread is running, this function call the connection's + /// Connection::Read(...) function to get any available. /// - /// If a read thread has been started, this function will check for - /// any cached bytes that have already been read and return any - /// currently available bytes. If no bytes are cached, it will wait - /// for the bytes to become available by listening for the \a - /// eBroadcastBitReadThreadGotBytes event. If this function consumes - /// all of the bytes in the cache, it will reset the - /// \a eBroadcastBitReadThreadGotBytes event bit. + /// If a read thread has been started, this function will check for any + /// cached bytes that have already been read and return any currently + /// available bytes. If no bytes are cached, it will wait for the bytes to + /// become available by listening for the \a eBroadcastBitReadThreadGotBytes + /// event. If this function consumes all of the bytes in the cache, it will + /// reset the \a eBroadcastBitReadThreadGotBytes event bit. /// /// @param[in] dst /// A destination buffer that must be at least \a dst_len bytes @@ -220,8 +214,8 @@ public: lldb::ConnectionStatus &status, Status *error_ptr); //------------------------------------------------------------------ - /// The actual write function that attempts to write to the - /// communications protocol. + /// The actual write function that attempts to write to the communications + /// protocol. /// /// Subclasses must override this function. /// @@ -242,11 +236,10 @@ public: //------------------------------------------------------------------ /// Sets the connection that it to be used by this class. /// - /// By making a communication class that uses different connections - /// it allows a single communication interface to negotiate and - /// change its connection without any interruption to the client. - /// It also allows the Communication class to be subclassed for - /// packet based communication. + /// By making a communication class that uses different connections it + /// allows a single communication interface to negotiate and change its + /// connection without any interruption to the client. It also allows the + /// Communication class to be subclassed for packet based communication. /// /// @param[in] connection /// A connection that this class will own and destroy. @@ -257,19 +250,19 @@ public: void SetConnection(Connection *connection); //------------------------------------------------------------------ - /// Starts a read thread whose sole purpose it to read bytes from - /// the current connection. This function will call connection's - /// read function: + /// Starts a read thread whose sole purpose it to read bytes from the + /// current connection. This function will call connection's read function: /// /// size_t Connection::Read (void *, size_t); /// /// When bytes are read and cached, this function will call: /// - /// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, bool + /// Communication::AppendBytesToCache (const uint8_t * bytes, size_t len, + /// bool /// broadcast); /// - /// Subclasses should override this function if they wish to override - /// the default action of caching the bytes and broadcasting a \b + /// Subclasses should override this function if they wish to override the + /// default action of caching the bytes and broadcasting a \b /// eBroadcastBitReadThreadGotBytes event. /// /// @return @@ -277,8 +270,8 @@ public: /// false otherwise. /// /// @see size_t Connection::Read (void *, size_t); - /// @see void Communication::AppendBytesToCache (const uint8_t * bytes, size_t - /// len, bool broadcast); + /// @see void Communication::AppendBytesToCache (const uint8_t * bytes, + /// size_t len, bool broadcast); //------------------------------------------------------------------ virtual bool StartReadThread(Status *error_ptr = nullptr); @@ -301,11 +294,10 @@ public: bool ReadThreadIsRunning(); //------------------------------------------------------------------ - /// The static read thread function. This function will call - /// the "DoRead" function continuously and wait for data to become - /// available. When data is received it will append the available - /// data to the internal cache and broadcast a - /// \b eBroadcastBitReadThreadGotBytes event. + /// The static read thread function. This function will call the "DoRead" + /// function continuously and wait for data to become available. When data + /// is received it will append the available data to the internal cache and + /// broadcast a \b eBroadcastBitReadThreadGotBytes event. /// /// @param[in] comm_ptr /// A pointer to an instance of this class. @@ -364,18 +356,17 @@ protected: lldb::ConnectionStatus &status, Status *error_ptr); //------------------------------------------------------------------ - /// Append new bytes that get read from the read thread into the - /// internal object byte cache. This will cause a \b - /// eBroadcastBitReadThreadGotBytes event to be broadcast if \a - /// broadcast is true. + /// Append new bytes that get read from the read thread into the internal + /// object byte cache. This will cause a \b eBroadcastBitReadThreadGotBytes + /// event to be broadcast if \a broadcast is true. /// - /// Subclasses can override this function in order to inspect the - /// received data and check if a packet is available. + /// Subclasses can override this function in order to inspect the received + /// data and check if a packet is available. /// - /// Subclasses can also still call this function from the - /// overridden method to allow the caching to correctly happen and - /// suppress the broadcasting of the \a eBroadcastBitReadThreadGotBytes - /// event by setting \a broadcast to false. + /// Subclasses can also still call this function from the overridden method + /// to allow the caching to correctly happen and suppress the broadcasting + /// of the \a eBroadcastBitReadThreadGotBytes event by setting \a broadcast + /// to false. /// /// @param[in] src /// A source buffer that must be at least \a src_len bytes @@ -389,9 +380,9 @@ protected: lldb::ConnectionStatus status); //------------------------------------------------------------------ - /// Get any available bytes from our data cache. If this call - /// empties the data cache, the \b eBroadcastBitReadThreadGotBytes event - /// will be reset to signify no more bytes are available. + /// Get any available bytes from our data cache. If this call empties the + /// data cache, the \b eBroadcastBitReadThreadGotBytes event will be reset + /// to signify no more bytes are available. /// /// @param[in] dst /// A destination buffer that must be at least \a dst_len bytes diff --git a/lldb/include/lldb/Core/Debugger.h b/lldb/include/lldb/Core/Debugger.h index 1b403cba705..cc7176e5c95 100644 --- a/lldb/include/lldb/Core/Debugger.h +++ b/lldb/include/lldb/Core/Debugger.h @@ -76,7 +76,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Debugger Debugger.h "lldb/Core/Debugger.h" -/// @brief A class to manage flag bits. +/// A class to manage flag bits. /// /// Provides a global root objects for the debugger core. //---------------------------------------------------------------------- @@ -169,10 +169,9 @@ public: //------------------------------------------------------------------ /// Get accessor for the target list. /// - /// The target list is part of the global debugger object. This - /// the single debugger shared instance to control where targets - /// get created and to allow for tracking and searching for targets - /// based on certain criteria. + /// The target list is part of the global debugger object. This the single + /// debugger shared instance to control where targets get created and to + /// allow for tracking and searching for targets based on certain criteria. /// /// @return /// A global shared target list. diff --git a/lldb/include/lldb/Core/EmulateInstruction.h b/lldb/include/lldb/Core/EmulateInstruction.h index 4bc6e7a1bea..5d23bcd7b96 100644 --- a/lldb/include/lldb/Core/EmulateInstruction.h +++ b/lldb/include/lldb/Core/EmulateInstruction.h @@ -48,62 +48,61 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class EmulateInstruction EmulateInstruction.h /// "lldb/Core/EmulateInstruction.h" -/// @brief A class that allows emulation of CPU opcodes. +/// A class that allows emulation of CPU opcodes. /// -/// This class is a plug-in interface that is accessed through the -/// standard static FindPlugin function call in the EmulateInstruction -/// class. The FindPlugin takes a target triple and returns a new object -/// if there is a plug-in that supports the architecture and OS. Four -/// callbacks and a baton are provided. The four callbacks are read -/// register, write register, read memory and write memory. +/// This class is a plug-in interface that is accessed through the standard +/// static FindPlugin function call in the EmulateInstruction class. The +/// FindPlugin takes a target triple and returns a new object if there is a +/// plug-in that supports the architecture and OS. Four callbacks and a baton +/// are provided. The four callbacks are read register, write register, read +/// memory and write memory. /// -/// This class is currently designed for these main use cases: -/// - Auto generation of Call Frame Information (CFI) from assembly code -/// - Predicting single step breakpoint locations -/// - Emulating instructions for breakpoint traps +/// This class is currently designed for these main use cases: - Auto +/// generation of Call Frame Information (CFI) from assembly code - Predicting +/// single step breakpoint locations - Emulating instructions for breakpoint +/// traps /// -/// Objects can be asked to read an instruction which will cause a call -/// to the read register callback to get the PC, followed by a read -/// memory call to read the opcode. If ReadInstruction () returns true, -/// then a call to EmulateInstruction::EvaluateInstruction () can be -/// made. At this point the EmulateInstruction subclass will use all of -/// the callbacks to emulate an instruction. +/// Objects can be asked to read an instruction which will cause a call to the +/// read register callback to get the PC, followed by a read memory call to +/// read the opcode. If ReadInstruction () returns true, then a call to +/// EmulateInstruction::EvaluateInstruction () can be made. At this point the +/// EmulateInstruction subclass will use all of the callbacks to emulate an +/// instruction. /// /// Clients that provide the callbacks can either do the read/write -/// registers/memory to actually emulate the instruction on a real or -/// virtual CPU, or watch for the EmulateInstruction::Context which -/// is context for the read/write register/memory which explains why -/// the callback is being called. Examples of a context are: -/// "pushing register 3 onto the stack at offset -12", or "adjusting -/// stack pointer by -16". This extra context allows the generation of +/// registers/memory to actually emulate the instruction on a real or virtual +/// CPU, or watch for the EmulateInstruction::Context which is context for the +/// read/write register/memory which explains why the callback is being +/// called. Examples of a context are: "pushing register 3 onto the stack at +/// offset -12", or "adjusting stack pointer by -16". This extra context +/// allows the generation of /// CFI information from assembly code without having to actually do /// the read/write register/memory. /// -/// Clients must be prepared that not all instructions for an -/// Instruction Set Architecture (ISA) will be emulated. +/// Clients must be prepared that not all instructions for an Instruction Set +/// Architecture (ISA) will be emulated. /// -/// Subclasses at the very least should implement the instructions that -/// save and restore registers onto the stack and adjustment to the stack -/// pointer. By just implementing a few instructions for an ISA that are -/// the typical prologue opcodes, you can then generate CFI using a -/// class that will soon be available. +/// Subclasses at the very least should implement the instructions that save +/// and restore registers onto the stack and adjustment to the stack pointer. +/// By just implementing a few instructions for an ISA that are the typical +/// prologue opcodes, you can then generate CFI using a class that will soon +/// be available. /// -/// Implementing all of the instructions that affect the PC can then -/// allow single step prediction support. +/// Implementing all of the instructions that affect the PC can then allow +/// single step prediction support. /// -/// Implementing all of the instructions allows for emulation of opcodes -/// for breakpoint traps and will pave the way for "thread centric" -/// debugging. The current debugging model is "process centric" where -/// all threads must be stopped when any thread is stopped; when -/// hitting software breakpoints we must disable the breakpoint by -/// restoring the original breakpoint opcode, single stepping and -/// restoring the breakpoint trap. If all threads were allowed to run -/// then other threads could miss the breakpoint. +/// Implementing all of the instructions allows for emulation of opcodes for +/// breakpoint traps and will pave the way for "thread centric" debugging. The +/// current debugging model is "process centric" where all threads must be +/// stopped when any thread is stopped; when hitting software breakpoints we +/// must disable the breakpoint by restoring the original breakpoint opcode, +/// single stepping and restoring the breakpoint trap. If all threads were +/// allowed to run then other threads could miss the breakpoint. /// -/// This class centralizes the code that usually is done in separate -/// code paths in a debugger (single step prediction, finding save -/// restore locations of registers for unwinding stack frame variables) -/// and emulating the instruction is just a bonus. +/// This class centralizes the code that usually is done in separate code +/// paths in a debugger (single step prediction, finding save restore +/// locations of registers for unwinding stack frame variables) and emulating +/// the instruction is just a bonus. //---------------------------------------------------------------------- class EmulateInstruction : public PluginInterface { diff --git a/lldb/include/lldb/Core/FileLineResolver.h b/lldb/include/lldb/Core/FileLineResolver.h index 54bce4fd2f4..855d749ed5d 100644 --- a/lldb/include/lldb/Core/FileLineResolver.h +++ b/lldb/include/lldb/Core/FileLineResolver.h @@ -28,9 +28,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class FileLineResolver FileLineResolver.h "lldb/Core/FileLineResolver.h" -/// @brief This class finds address for source file and line. Optionally, it -/// will look for inlined -/// instances of the file and line specification. +/// This class finds address for source file and line. Optionally, it will +/// look for inlined instances of the file and line specification. //---------------------------------------------------------------------- class FileLineResolver : public Searcher { diff --git a/lldb/include/lldb/Core/FileSpecList.h b/lldb/include/lldb/Core/FileSpecList.h index 4b3b29b8382..713ed2aaffc 100644 --- a/lldb/include/lldb/Core/FileSpecList.h +++ b/lldb/include/lldb/Core/FileSpecList.h @@ -25,7 +25,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class FileSpecList FileSpecList.h "lldb/Core/FileSpecList.h" -/// @brief A file collection class. +/// A file collection class. /// /// A class that contains a mutable list of FileSpec objects. //---------------------------------------------------------------------- @@ -56,8 +56,7 @@ public: //------------------------------------------------------------------ /// Assignment operator. /// - /// Replace the file list in this object with the file list from - /// \a rhs. + /// Replace the file list in this object with the file list from \a rhs. /// /// @param[in] rhs /// A file list object to copy. @@ -80,8 +79,8 @@ public: //------------------------------------------------------------------ /// Append a FileSpec object if unique. /// - /// Appends \a file to the end of the file list if it doesn't - /// already exist in the file list. + /// Appends \a file to the end of the file list if it doesn't already exist + /// in the file list. /// /// @param[in] file /// A new file to append to this file list. @@ -107,8 +106,8 @@ public: //------------------------------------------------------------------ /// Find a file index. /// - /// Find the index of the file in the file spec list that matches - /// \a file starting \a idx entries into the file spec list. + /// Find the index of the file in the file spec list that matches \a file + /// starting \a idx entries into the file spec list. /// /// @param[in] idx /// An index into the file list. @@ -128,10 +127,9 @@ public: //------------------------------------------------------------------ /// Get file at index. /// - /// Gets a file from the file list. If \a idx is not a valid index, - /// an empty FileSpec object will be returned. The file objects - /// that are returned can be tested using - /// FileSpec::operator void*(). + /// Gets a file from the file list. If \a idx is not a valid index, an empty + /// FileSpec object will be returned. The file objects that are returned can + /// be tested using FileSpec::operator void*(). /// /// @param[in] idx /// An index into the file list. @@ -146,8 +144,8 @@ public: //------------------------------------------------------------------ /// Get file specification pointer at index. /// - /// Gets a file from the file list. The file objects that are - /// returned can be tested using FileSpec::operator void*(). + /// Gets a file from the file list. The file objects that are returned can + /// be tested using FileSpec::operator void*(). /// /// @param[in] idx /// An index into the file list. @@ -161,9 +159,9 @@ public: //------------------------------------------------------------------ /// Get the memory cost of this object. /// - /// Return the size in bytes that this object takes in memory. This - /// returns the size in bytes of this object, not any shared string - /// values it may refer to. + /// Return the size in bytes that this object takes in memory. This returns + /// the size in bytes of this object, not any shared string values it may + /// refer to. /// /// @return /// The number of bytes that this object occupies in memory. diff --git a/lldb/include/lldb/Core/Mangled.h b/lldb/include/lldb/Core/Mangled.h index 22778fabe63..d263297ecfc 100644 --- a/lldb/include/lldb/Core/Mangled.h +++ b/lldb/include/lldb/Core/Mangled.h @@ -28,15 +28,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Mangled Mangled.h "lldb/Core/Mangled.h" -/// @brief A class that handles mangled names. +/// A class that handles mangled names. /// -/// Designed to handle mangled names. The demangled version of any names -/// will be computed when the demangled name is accessed through the -/// Demangled() acccessor. This class can also tokenize the demangled -/// version of the name for powerful searches. Functions and symbols -/// could make instances of this class for their mangled names. Uniqued -/// string pools are used for the mangled, demangled, and token string -/// values to allow for faster comparisons and for efficient memory use. +/// Designed to handle mangled names. The demangled version of any names will +/// be computed when the demangled name is accessed through the Demangled() +/// acccessor. This class can also tokenize the demangled version of the name +/// for powerful searches. Functions and symbols could make instances of this +/// class for their mangled names. Uniqued string pools are used for the +/// mangled, demangled, and token string values to allow for faster +/// comparisons and for efficient memory use. //---------------------------------------------------------------------- class Mangled { public: @@ -91,16 +91,16 @@ public: //---------------------------------------------------------------------- /// Destructor /// - /// Releases its ref counts on the mangled and demangled strings that - /// live in the global string pool. + /// Releases its ref counts on the mangled and demangled strings that live + /// in the global string pool. //---------------------------------------------------------------------- ~Mangled(); //---------------------------------------------------------------------- /// Convert to pointer operator. /// - /// This allows code to check a Mangled object to see if it contains - /// a valid mangled name using code such as: + /// This allows code to check a Mangled object to see if it contains a valid + /// mangled name using code such as: /// /// @code /// Mangled mangled(...); @@ -117,8 +117,8 @@ public: //---------------------------------------------------------------------- /// Logical NOT operator. /// - /// This allows code to check a Mangled object to see if it contains - /// an empty mangled name using code such as: + /// This allows code to check a Mangled object to see if it contains an + /// empty mangled name using code such as: /// /// @code /// Mangled mangled(...); @@ -158,8 +158,8 @@ public: //---------------------------------------------------------------------- /// Dump a description of this object to a Stream \a s. /// - /// Dump a Mangled object to stream \a s. We don't force our - /// demangled name to be computed currently (we don't use the accessor). + /// Dump a Mangled object to stream \a s. We don't force our demangled name + /// to be computed currently (we don't use the accessor). /// /// @param[in] s /// The stream to which to dump the object description. @@ -245,9 +245,9 @@ public: //---------------------------------------------------------------------- /// Get the memory cost of this object. /// - /// Return the size in bytes that this object takes in memory. This - /// returns the size in bytes of this object, not any shared string - /// values it may refer to. + /// Return the size in bytes that this object takes in memory. This returns + /// the size in bytes of this object, not any shared string values it may + /// refer to. /// /// @return /// The number of bytes that this object occupies in memory. @@ -259,8 +259,8 @@ public: //---------------------------------------------------------------------- /// Set the string value in this object. /// - /// If \a is_mangled is \b true, then the mangled named is set to \a - /// name, else the demangled name is set to \a name. + /// If \a is_mangled is \b true, then the mangled named is set to \a name, + /// else the demangled name is set to \a name. /// /// @param[in] name /// The already const version of the name for this object. @@ -285,14 +285,14 @@ public: //---------------------------------------------------------------------- /// Try to guess the language from the mangling. /// - /// For a mangled name to have a language it must have both a mangled - /// and a demangled name and it can be guessed from the mangling what - /// the language is. Note: this will return C++ for any language that - /// uses Itanium ABI mangling. + /// For a mangled name to have a language it must have both a mangled and a + /// demangled name and it can be guessed from the mangling what the language + /// is. Note: this will return C++ for any language that uses Itanium ABI + /// mangling. /// - /// Standard C function names will return eLanguageTypeUnknown because - /// they aren't mangled and it isn't clear what language the name - /// represents (there will be no mangled name). + /// Standard C function names will return eLanguageTypeUnknown because they + /// aren't mangled and it isn't clear what language the name represents + /// (there will be no mangled name). /// /// @return /// The language for the mangled/demangled name, eLanguageTypeUnknown diff --git a/lldb/include/lldb/Core/Module.h b/lldb/include/lldb/Core/Module.h index 6adcc52d0c4..0eaafc61fb0 100644 --- a/lldb/include/lldb/Core/Module.h +++ b/lldb/include/lldb/Core/Module.h @@ -93,22 +93,20 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Module Module.h "lldb/Core/Module.h" -/// @brief A class that describes an executable image and its associated +/// A class that describes an executable image and its associated /// object and symbol files. /// /// The module is designed to be able to select a single slice of an -/// executable image as it would appear on disk and during program -/// execution. +/// executable image as it would appear on disk and during program execution. /// /// Modules control when and if information is parsed according to which /// accessors are called. For example the object file (ObjectFile) -/// representation will only be parsed if the object file is requested -/// using the Module::GetObjectFile() is called. The debug symbols -/// will only be parsed if the symbol vendor (SymbolVendor) is -/// requested using the Module::GetSymbolVendor() is called. +/// representation will only be parsed if the object file is requested using +/// the Module::GetObjectFile() is called. The debug symbols will only be +/// parsed if the symbol vendor (SymbolVendor) is requested using the +/// Module::GetSymbolVendor() is called. /// -/// The module will parse more detailed information as more queries are -/// made. +/// The module will parse more detailed information as more queries are made. //---------------------------------------------------------------------- class Module : public std::enable_shared_from_this<Module>, public SymbolContextScope { @@ -128,8 +126,8 @@ public: //------------------------------------------------------------------ /// Construct with file specification and architecture. /// - /// Clients that wish to share modules with other targets should - /// use ModuleList::GetSharedModule(). + /// Clients that wish to share modules with other targets should use + /// ModuleList::GetSharedModule(). /// /// @param[in] file_spec /// The file specification for the on disk representation of @@ -168,13 +166,13 @@ public: bool MatchesModuleSpec(const ModuleSpec &module_ref); //------------------------------------------------------------------ - /// Set the load address for all sections in a module to be the - /// file address plus \a slide. + /// Set the load address for all sections in a module to be the file address + /// plus \a slide. /// - /// Many times a module will be loaded in a target with a constant - /// offset applied to all top level sections. This function can - /// set the load address for all top level sections to be the - /// section file address + offset. + /// Many times a module will be loaded in a target with a constant offset + /// applied to all top level sections. This function can set the load + /// address for all top level sections to be the section file address + + /// offset. /// /// @param[in] target /// The target in which to apply the section load addresses. @@ -224,19 +222,18 @@ public: //------------------------------------------------------------------ /// Get the module path and object name. /// - /// Modules can refer to object files. In this case the specification - /// is simple and would return the path to the file: + /// Modules can refer to object files. In this case the specification is + /// simple and would return the path to the file: /// /// "/usr/lib/foo.dylib" /// - /// Modules can be .o files inside of a BSD archive (.a file). In - /// this case, the object specification will look like: + /// Modules can be .o files inside of a BSD archive (.a file). In this case, + /// the object specification will look like: /// /// "/usr/lib/foo.a(bar.o)" /// - /// There are many places where logging wants to log this fully - /// qualified specification, so we centralize this functionality - /// here. + /// There are many places where logging wants to log this fully qualified + /// specification, so we centralize this functionality here. /// /// @return /// The object path + object name if there is one. @@ -246,11 +243,10 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. The dumped content will be only what has - /// been loaded or parsed up to this point at which this function - /// is called, so this is a good way to see what has been parsed - /// in a module. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. The dumped content will be only what has been loaded or parsed up + /// to this point at which this function is called, so this is a good way to + /// see what has been parsed in a module. /// /// @param[in] s /// The stream to which to dump the object description. @@ -315,8 +311,8 @@ public: //------------------------------------------------------------------ /// Find compile units by partial or full path. /// - /// Finds all compile units that match \a path in all of the modules - /// and returns the results in \a sc_list. + /// Finds all compile units that match \a path in all of the modules and + /// returns the results in \a sc_list. /// /// @param[in] path /// The name of the function we are looking for. @@ -341,8 +337,7 @@ public: /// /// If the function is an inlined function, it will have a block, /// representing the inlined function, and the function will be the - /// containing function. If it is not inlined, then the block will - /// be NULL. + /// containing function. If it is not inlined, then the block will be NULL. /// /// @param[in] name /// The name of the compile unit we are looking for. @@ -378,8 +373,7 @@ public: /// /// If the function is an inlined function, it will have a block, /// representing the inlined function, and the function will be the - /// containing function. If it is not inlined, then the block will - /// be NULL. + /// containing function. If it is not inlined, then the block will be NULL. /// /// @param[in] regex /// A regular expression to use when matching the name. @@ -486,22 +480,20 @@ public: //------------------------------------------------------------------ /// Find types by name. /// - /// Type lookups in modules go through the SymbolVendor (which will - /// use one or more SymbolFile subclasses). The SymbolFile needs to - /// be able to lookup types by basename and not the fully qualified - /// typename. This allows the type accelerator tables to stay small, - /// even with heavily templatized C++. The type search will then - /// narrow down the search results. If "exact_match" is true, then - /// the type search will only match exact type name matches. If - /// "exact_match" is false, the type will match as long as the base - /// typename matches and as long as any immediate containing - /// namespaces/class scopes that are specified match. So to search - /// for a type "d" in "b::c", the name "b::c::d" can be specified - /// and it will match any class/namespace "b" which contains a - /// class/namespace "c" which contains type "d". We do this to - /// allow users to not always have to specify complete scoping on - /// all expressions, but it also allows for exact matching when - /// required. + /// Type lookups in modules go through the SymbolVendor (which will use one + /// or more SymbolFile subclasses). The SymbolFile needs to be able to + /// lookup types by basename and not the fully qualified typename. This + /// allows the type accelerator tables to stay small, even with heavily + /// templatized C++. The type search will then narrow down the search + /// results. If "exact_match" is true, then the type search will only match + /// exact type name matches. If "exact_match" is false, the type will match + /// as long as the base typename matches and as long as any immediate + /// containing namespaces/class scopes that are specified match. So to + /// search for a type "d" in "b::c", the name "b::c::d" can be specified and + /// it will match any class/namespace "b" which contains a class/namespace + /// "c" which contains type "d". We do this to allow users to not always + /// have to specify complete scoping on all expressions, but it also allows + /// for exact matching when required. /// /// @param[in] sc /// A symbol context that scopes where to extract a type list @@ -534,9 +526,9 @@ public: const ConstString &type_name, bool exact_match); //------------------------------------------------------------------ - /// Find types by name that are in a namespace. This function is - /// used by the expression parser when searches need to happen in - /// an exact namespace scope. + /// Find types by name that are in a namespace. This function is used by the + /// expression parser when searches need to happen in an exact namespace + /// scope. /// /// @param[in] sc /// A symbol context that scopes where to extract a type list @@ -571,9 +563,9 @@ public: //------------------------------------------------------------------ /// Get const accessor for the module file specification. /// - /// This function returns the file for the module on the host system - /// that is running LLDB. This can differ from the path on the - /// platform since we might be doing remote debugging. + /// This function returns the file for the module on the host system that is + /// running LLDB. This can differ from the path on the platform since we + /// might be doing remote debugging. /// /// @return /// A const reference to the file specification object. @@ -583,14 +575,13 @@ public: //------------------------------------------------------------------ /// Get accessor for the module platform file specification. /// - /// Platform file refers to the path of the module as it is known on - /// the remote system on which it is being debugged. For local - /// debugging this is always the same as Module::GetFileSpec(). But - /// remote debugging might mention a file "/usr/lib/liba.dylib" - /// which might be locally downloaded and cached. In this case the - /// platform file could be something like: - /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" - /// The file could also be cached in a local developer kit directory. + /// Platform file refers to the path of the module as it is known on the + /// remote system on which it is being debugged. For local debugging this is + /// always the same as Module::GetFileSpec(). But remote debugging might + /// mention a file "/usr/lib/liba.dylib" which might be locally downloaded + /// and cached. In this case the platform file could be something like: + /// "/tmp/lldb/platform-cache/remote.host.computer/usr/lib/liba.dylib" The + /// file could also be cached in a local developer kit directory. /// /// @return /// A const reference to the file specification object. @@ -630,8 +621,8 @@ public: } //------------------------------------------------------------------ - /// Tells whether this module is capable of being the main executable - /// for a process. + /// Tells whether this module is capable of being the main executable for a + /// process. /// /// @return /// \b true if it is, \b false otherwise. @@ -639,9 +630,9 @@ public: bool IsExecutable(); //------------------------------------------------------------------ - /// Tells whether this module has been loaded in the target passed in. - /// This call doesn't distinguish between whether the module is loaded - /// by the dynamic loader, or by a "target module add" type call. + /// Tells whether this module has been loaded in the target passed in. This + /// call doesn't distinguish between whether the module is loaded by the + /// dynamic loader, or by a "target module add" type call. /// /// @param[in] target /// The target to check whether this is loaded in. @@ -672,9 +663,8 @@ public: //------------------------------------------------------------------ /// Get the object file representation for the current architecture. /// - /// If the object file has not been located or parsed yet, this - /// function will find the best ObjectFile plug-in that can parse - /// Module::m_file. + /// If the object file has not been located or parsed yet, this function + /// will find the best ObjectFile plug-in that can parse Module::m_file. /// /// @return /// If Module::m_file does not exist, or no plug-in was found @@ -687,12 +677,12 @@ public: virtual ObjectFile *GetObjectFile(); //------------------------------------------------------------------ - /// Get the unified section list for the module. This is the section - /// list created by the module's object file and any debug info and - /// symbol files created by the symbol vendor. + /// Get the unified section list for the module. This is the section list + /// created by the module's object file and any debug info and symbol files + /// created by the symbol vendor. /// - /// If the symbol vendor has not been loaded yet, this function - /// will return the section list for the object file. + /// If the symbol vendor has not been loaded yet, this function will return + /// the section list for the object file. /// /// @return /// Unified module section list. @@ -700,13 +690,13 @@ public: virtual SectionList *GetSectionList(); //------------------------------------------------------------------ - /// Notify the module that the file addresses for the Sections have - /// been updated. + /// Notify the module that the file addresses for the Sections have been + /// updated. /// - /// If the Section file addresses for a module are updated, this - /// method should be called. Any parts of the module, object file, - /// or symbol file that has cached those file addresses must invalidate - /// or update its cache. + /// If the Section file addresses for a module are updated, this method + /// should be called. Any parts of the module, object file, or symbol file + /// that has cached those file addresses must invalidate or update its + /// cache. //------------------------------------------------------------------ virtual void SectionFileAddressesChanged(); @@ -715,12 +705,11 @@ public: //------------------------------------------------------------------ /// Load an object file from memory. /// - /// If available, the size of the object file in memory may be - /// passed to avoid additional round trips to process memory. - /// If the size is not provided, a default value is used. This - /// value should be large enough to enable the ObjectFile plugins - /// to read the header of the object file without going back to the - /// process. + /// If available, the size of the object file in memory may be passed to + /// avoid additional round trips to process memory. If the size is not + /// provided, a default value is used. This value should be large enough to + /// enable the ObjectFile plugins to read the header of the object file + /// without going back to the process. /// /// @return /// The object file loaded from memory or nullptr, if the operation @@ -732,9 +721,8 @@ public: //------------------------------------------------------------------ /// Get the symbol vendor interface for the current architecture. /// - /// If the symbol vendor file has not been located yet, this - /// function will find the best SymbolVendor plug-in that can - /// use the current object file. + /// If the symbol vendor file has not been located yet, this function will + /// find the best SymbolVendor plug-in that can use the current object file. /// /// @return /// If this module does not have a valid object file, or no @@ -759,9 +747,9 @@ public: //------------------------------------------------------------------ /// Get a pointer to the UUID value contained in this object. /// - /// If the executable image file doesn't not have a UUID value built - /// into the file format, an MD5 checksum of the entire file, or - /// slice of the file for the current architecture should be used. + /// If the executable image file doesn't not have a UUID value built into + /// the file format, an MD5 checksum of the entire file, or slice of the + /// file for the current architecture should be used. /// /// @return /// A const pointer to the internal copy of the UUID value in @@ -774,14 +762,13 @@ public: /// A debugging function that will cause everything in a module to /// be parsed. /// - /// All compile units will be parsed, along with all globals and - /// static variables and all functions for those compile units. - /// All types, scopes, local variables, static variables, global - /// variables, and line tables will be parsed. This can be used - /// prior to dumping a module to see a complete list of the - /// resulting debug information that gets parsed, or as a debug - /// function to ensure that the module can consume all of the - /// debug data the symbol vendor provides. + /// All compile units will be parsed, along with all globals and static + /// variables and all functions for those compile units. All types, scopes, + /// local variables, static variables, global variables, and line tables + /// will be parsed. This can be used prior to dumping a module to see a + /// complete list of the resulting debug information that gets parsed, or as + /// a debug function to ensure that the module can consume all of the debug + /// data the symbol vendor provides. //------------------------------------------------------------------ void ParseAllDebugSymbols(); @@ -790,17 +777,16 @@ public: //------------------------------------------------------------------ /// Resolve the symbol context for the given address. /// - /// Tries to resolve the matching symbol context based on a lookup - /// from the current symbol vendor. If the lazy lookup fails, - /// an attempt is made to parse the eh_frame section to handle - /// stripped symbols. If this fails, an attempt is made to resolve - /// the symbol to the previous address to handle the case of a - /// function with a tail call. + /// Tries to resolve the matching symbol context based on a lookup from the + /// current symbol vendor. If the lazy lookup fails, an attempt is made to + /// parse the eh_frame section to handle stripped symbols. If this fails, + /// an attempt is made to resolve the symbol to the previous address to + /// handle the case of a function with a tail call. /// - /// Use properties of the modified SymbolContext to inspect any - /// resolved target, module, compilation unit, symbol, function, - /// function block or line entry. Use the return value to determine - /// which of these properties have been modified. + /// Use properties of the modified SymbolContext to inspect any resolved + /// target, module, compilation unit, symbol, function, function block or + /// line entry. Use the return value to determine which of these properties + /// have been modified. /// /// @param[in] so_addr /// A load address to resolve. @@ -835,15 +821,14 @@ public: //------------------------------------------------------------------ /// Resolve items in the symbol context for a given file and line. /// - /// Tries to resolve \a file_path and \a line to a list of matching - /// symbol contexts. + /// Tries to resolve \a file_path and \a line to a list of matching symbol + /// contexts. /// - /// The line table entries contains addresses that can be used to - /// further resolve the values in each match: the function, block, - /// symbol. Care should be taken to minimize the amount of - /// information that is requested to only what is needed -- - /// typically the module, compile unit, line table and line table - /// entry are sufficient. + /// The line table entries contains addresses that can be used to further + /// resolve the values in each match: the function, block, symbol. Care + /// should be taken to minimize the amount of information that is requested + /// to only what is needed -- typically the module, compile unit, line table + /// and line table entry are sufficient. /// /// @param[in] file_path /// A path to a source file to match. If \a file_path does not @@ -882,15 +867,14 @@ public: //------------------------------------------------------------------ /// Resolve items in the symbol context for a given file and line. /// - /// Tries to resolve \a file_spec and \a line to a list of matching - /// symbol contexts. + /// Tries to resolve \a file_spec and \a line to a list of matching symbol + /// contexts. /// - /// The line table entries contains addresses that can be used to - /// further resolve the values in each match: the function, block, - /// symbol. Care should be taken to minimize the amount of - /// information that is requested to only what is needed -- - /// typically the module, compile unit, line table and line table - /// entry are sufficient. + /// The line table entries contains addresses that can be used to further + /// resolve the values in each match: the function, block, symbol. Care + /// should be taken to minimize the amount of information that is requested + /// to only what is needed -- typically the module, compile unit, line table + /// and line table entry are sufficient. /// /// @param[in] file_spec /// A file spec to a source file to match. If \a file_path does @@ -976,14 +960,13 @@ public: } //------------------------------------------------------------------ - /// Finds a source file given a file spec using the module source - /// path remappings (if any). + /// Finds a source file given a file spec using the module source path + /// remappings (if any). /// /// Tries to resolve \a orig_spec by checking the module source path - /// remappings. It makes sure the file exists, so this call can be - /// expensive if the remappings are on a network file system, so - /// use this function sparingly (not in a tight debug info parsing - /// loop). + /// remappings. It makes sure the file exists, so this call can be expensive + /// if the remappings are on a network file system, so use this function + /// sparingly (not in a tight debug info parsing loop). /// /// @param[in] orig_spec /// The original source file path to try and remap. @@ -1001,9 +984,9 @@ public: //------------------------------------------------------------------ /// Remaps a source file given \a path into \a new_path. /// - /// Remaps \a path if any source remappings match. This function - /// does NOT stat the file system so it can be used in tight loops - /// where debug info is being parsed. + /// Remaps \a path if any source remappings match. This function does NOT + /// stat the file system so it can be used in tight loops where debug info + /// is being parsed. /// /// @param[in] path /// The original source file path to try and remap. @@ -1020,27 +1003,26 @@ public: //---------------------------------------------------------------------- /// @class LookupInfo Module.h "lldb/Core/Module.h" - /// @brief A class that encapsulates name lookup information. - /// - /// Users can type a wide variety of partial names when setting - /// breakpoints by name or when looking for functions by name. - /// SymbolVendor and SymbolFile objects are only required to implement - /// name lookup for function basenames and for fully mangled names. - /// This means if the user types in a partial name, we must reduce this - /// to a name lookup that will work with all SymbolFile objects. So we - /// might reduce a name lookup to look for a basename, and then prune - /// out any results that don't match. - /// - /// The "m_name" member variable represents the name as it was typed - /// by the user. "m_lookup_name" will be the name we actually search - /// for through the symbol or objects files. Lanaguage is included in - /// case we need to filter results by language at a later date. The - /// "m_name_type_mask" member variable tells us what kinds of names we - /// are looking for and can help us prune out unwanted results. + /// A class that encapsulates name lookup information. + /// + /// Users can type a wide variety of partial names when setting breakpoints + /// by name or when looking for functions by name. SymbolVendor and + /// SymbolFile objects are only required to implement name lookup for + /// function basenames and for fully mangled names. This means if the user + /// types in a partial name, we must reduce this to a name lookup that will + /// work with all SymbolFile objects. So we might reduce a name lookup to + /// look for a basename, and then prune out any results that don't match. + /// + /// The "m_name" member variable represents the name as it was typed by the + /// user. "m_lookup_name" will be the name we actually search for through + /// the symbol or objects files. Lanaguage is included in case we need to + /// filter results by language at a later date. The "m_name_type_mask" + /// member variable tells us what kinds of names we are looking for and can + /// help us prune out unwanted results. /// /// Function lookups are done in Module.cpp, ModuleList.cpp and in - /// BreakpointResolverName.cpp and they all now use this class to do - /// lookups correctly. + /// BreakpointResolverName.cpp and they all now use this class to do lookups + /// correctly. //---------------------------------------------------------------------- class LookupInfo { public: @@ -1139,9 +1121,9 @@ protected: /// /// Tries to resolve \a vm_addr as a file address (if \a /// vm_addr_is_file_addr is true) or as a load address if \a - /// vm_addr_is_file_addr is false) in the symbol vendor. - /// \a resolve_scope indicates what clients wish to resolve - /// and can be used to limit the scope of what is parsed. + /// vm_addr_is_file_addr is false) in the symbol vendor. \a resolve_scope + /// indicates what clients wish to resolve and can be used to limit the + /// scope of what is parsed. /// /// @param[in] vm_addr /// The load virtual address to resolve. diff --git a/lldb/include/lldb/Core/ModuleChild.h b/lldb/include/lldb/Core/ModuleChild.h index 8f2985c8185..73438040c35 100644 --- a/lldb/include/lldb/Core/ModuleChild.h +++ b/lldb/include/lldb/Core/ModuleChild.h @@ -16,7 +16,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ModuleChild ModuleChild.h "lldb/Core/ModuleChild.h" -/// @brief A mix in class that contains a pointer back to the module +/// A mix in class that contains a pointer back to the module /// that owns the object which inherits from it. //---------------------------------------------------------------------- class ModuleChild { diff --git a/lldb/include/lldb/Core/ModuleList.h b/lldb/include/lldb/Core/ModuleList.h index b7c2bac064c..a3a4aab7c65 100644 --- a/lldb/include/lldb/Core/ModuleList.h +++ b/lldb/include/lldb/Core/ModuleList.h @@ -86,10 +86,10 @@ public: //---------------------------------------------------------------------- /// @class ModuleList ModuleList.h "lldb/Core/ModuleList.h" -/// @brief A collection class for Module objects. +/// A collection class for Module objects. /// -/// Modules in the module collection class are stored as reference -/// counted shared pointers to Module objects. +/// Modules in the module collection class are stored as reference counted +/// shared pointers to Module objects. //---------------------------------------------------------------------- class ModuleList { public: @@ -117,8 +117,7 @@ public: //------------------------------------------------------------------ /// Copy Constructor. /// - /// Creates a new module list object with a copy of the modules from - /// \a rhs. + /// Creates a new module list object with a copy of the modules from \a rhs. /// /// @param[in] rhs /// Another module list object. @@ -156,9 +155,9 @@ public: void Append(const lldb::ModuleSP &module_sp); //------------------------------------------------------------------ - /// Append a module to the module list and remove any equivalent - /// modules. Equivalent modules are ones whose file, platform file - /// and architecture matches. + /// Append a module to the module list and remove any equivalent modules. + /// Equivalent modules are ones whose file, platform file and architecture + /// matches. /// /// Replaces the module to the collection. /// @@ -179,27 +178,27 @@ public: //------------------------------------------------------------------ /// Clear the object's state. /// - /// Clears the list of modules and releases a reference to each - /// module object and if the reference count goes to zero, the - /// module will be deleted. + /// Clears the list of modules and releases a reference to each module + /// object and if the reference count goes to zero, the module will be + /// deleted. //------------------------------------------------------------------ void Clear(); //------------------------------------------------------------------ /// Clear the object's state. /// - /// Clears the list of modules and releases a reference to each - /// module object and if the reference count goes to zero, the - /// module will be deleted. Also release all memory that might be - /// held by any collection classes (like std::vector) + /// Clears the list of modules and releases a reference to each module + /// object and if the reference count goes to zero, the module will be + /// deleted. Also release all memory that might be held by any collection + /// classes (like std::vector) //------------------------------------------------------------------ void Destroy(); //------------------------------------------------------------------ /// Dump the description of each module contained in this list. /// - /// Dump the description of each module contained in this list to - /// the supplied stream \a s. + /// Dump the description of each module contained in this list to the + /// supplied stream \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -230,8 +229,8 @@ public: //------------------------------------------------------------------ /// Get the module shared pointer for the module at index \a idx without - /// acquiring the ModuleList mutex. This MUST already have been - /// acquired with ModuleList::GetMutex and locked for this call to be safe. + /// acquiring the ModuleList mutex. This MUST already have been acquired + /// with ModuleList::GetMutex and locked for this call to be safe. /// /// @param[in] idx /// An index into this module collection. @@ -259,9 +258,9 @@ public: Module *GetModulePointerAtIndex(size_t idx) const; //------------------------------------------------------------------ - /// Get the module pointer for the module at index \a idx without - /// acquiring the ModuleList mutex. This MUST already have been - /// acquired with ModuleList::GetMutex and locked for this call to be safe. + /// Get the module pointer for the module at index \a idx without acquiring + /// the ModuleList mutex. This MUST already have been acquired with + /// ModuleList::GetMutex and locked for this call to be safe. /// /// @param[in] idx /// An index into this module collection. @@ -277,8 +276,8 @@ public: //------------------------------------------------------------------ /// Find compile units by partial or full path. /// - /// Finds all compile units that match \a path in all of the modules - /// and returns the results in \a sc_list. + /// Finds all compile units that match \a path in all of the modules and + /// returns the results in \a sc_list. /// /// @param[in] path /// The name of the compile unit we are looking for. @@ -372,8 +371,7 @@ public: VariableList &variable_list) const; //------------------------------------------------------------------ - /// Finds the first module whose file specification matches \a - /// file_spec. + /// Finds the first module whose file specification matches \a file_spec. /// /// @param[in] file_spec_ptr /// A file specification object to match against the Module's diff --git a/lldb/include/lldb/Core/SearchFilter.h b/lldb/include/lldb/Core/SearchFilter.h index c6434208215..2e641983dc7 100644 --- a/lldb/include/lldb/Core/SearchFilter.h +++ b/lldb/include/lldb/Core/SearchFilter.h @@ -52,9 +52,9 @@ class Target; namespace lldb_private { //---------------------------------------------------------------------- -/// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h" -/// @brief Class that is driven by the SearchFilter to search the -/// SymbolContext space of the target program. +/// @class Searcher SearchFilter.h "lldb/Core/SearchFilter.h" Class that is +/// driven by the SearchFilter to search the SymbolContext space of the target +/// program. //---------------------------------------------------------------------- //---------------------------------------------------------------------- @@ -99,10 +99,10 @@ public: }; //---------------------------------------------------------------------- -/// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h" -/// @brief Class descends through the SymbolContext space of the target, -/// applying a filter at each stage till it reaches the depth specified by -/// the GetDepth method of the searcher, and calls its callback at that point. +/// @class SearchFilter SearchFilter.h "lldb/Core/SearchFilter.h" Class +/// descends through the SymbolContext space of the target, applying a filter +/// at each stage till it reaches the depth specified by the GetDepth method +/// of the searcher, and calls its callback at that point. //---------------------------------------------------------------------- //---------------------------------------------------------------------- @@ -110,15 +110,12 @@ public: /// Provides the callback and search depth for the SearchFilter search. /// /// The search is done by cooperation between the search filter and the -/// searcher. -/// The search filter does the heavy work of recursing through the SymbolContext -/// space of the target program's symbol space. The Searcher specifies the -/// depth -/// at which it wants its callback to be invoked. Note that since the -/// resolution -/// of the Searcher may be greater than that of the SearchFilter, before the -/// Searcher qualifies an address it should pass it to "AddressPasses." -/// The default implementation is "Everything Passes." +/// searcher. The search filter does the heavy work of recursing through the +/// SymbolContext space of the target program's symbol space. The Searcher +/// specifies the depth at which it wants its callback to be invoked. Note +/// that since the resolution of the Searcher may be greater than that of the +/// SearchFilter, before the Searcher qualifies an address it should pass it +/// to "AddressPasses." The default implementation is "Everything Passes." //---------------------------------------------------------------------- class SearchFilter { @@ -172,8 +169,8 @@ public: virtual bool AddressPasses(Address &addr); //------------------------------------------------------------------ - /// Call this method with a FileSpec to see if \a file spec passes the filter - /// as the name of a compilation unit. + /// Call this method with a FileSpec to see if \a file spec passes the + /// filter as the name of a compilation unit. /// /// @param[in] fileSpec /// The file spec to check against the filter. @@ -218,11 +215,10 @@ public: virtual void SearchInModuleList(Searcher &searcher, ModuleList &modules); //------------------------------------------------------------------ - /// This determines which items are REQUIRED for the filter to pass. - /// For instance, if you are filtering by Compilation Unit, obviously - /// symbols that have no compilation unit can't pass So return - /// eSymbolContextCU - /// and search callbacks can then short cut the search to avoid looking at + /// This determines which items are REQUIRED for the filter to pass. For + /// instance, if you are filtering by Compilation Unit, obviously symbols + /// that have no compilation unit can't pass So return eSymbolContextCU and + /// search callbacks can then short cut the search to avoid looking at /// things that obviously won't pass. /// /// @return @@ -332,9 +328,9 @@ private: //---------------------------------------------------------------------- /// @class SearchFilterForUnconstrainedSearches SearchFilter.h -/// "lldb/Core/SearchFilter.h" -/// @brief This is a SearchFilter that searches through all modules. It also -/// consults the Target::ModuleIsExcludedForUnconstrainedSearches. +/// "lldb/Core/SearchFilter.h" This is a SearchFilter that searches through +/// all modules. It also consults the +/// Target::ModuleIsExcludedForUnconstrainedSearches. //---------------------------------------------------------------------- class SearchFilterForUnconstrainedSearches : public SearchFilter { public: @@ -359,8 +355,8 @@ protected: }; //---------------------------------------------------------------------- -/// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h" -/// @brief This is a SearchFilter that restricts the search to a given module. +/// @class SearchFilterByModule SearchFilter.h "lldb/Core/SearchFilter.h" This +/// is a SearchFilter that restricts the search to a given module. //---------------------------------------------------------------------- class SearchFilterByModule : public SearchFilter { diff --git a/lldb/include/lldb/Expression/DWARFExpression.h b/lldb/include/lldb/Expression/DWARFExpression.h index 5b149e08eb2..b4bd9697da5 100644 --- a/lldb/include/lldb/Expression/DWARFExpression.h +++ b/lldb/include/lldb/Expression/DWARFExpression.h @@ -23,17 +23,17 @@ class DWARFUnit; namespace lldb_private { //---------------------------------------------------------------------- -/// @class DWARFExpression DWARFExpression.h "lldb/Expression/DWARFExpression.h" -/// @brief Encapsulates a DWARF location expression and interprets it. +/// @class DWARFExpression DWARFExpression.h +/// "lldb/Expression/DWARFExpression.h" Encapsulates a DWARF location +/// expression and interprets it. /// /// DWARF location expressions are used in two ways by LLDB. The first -/// use is to find entities specified in the debug information, since -/// their locations are specified in precisely this language. The second -/// is to interpret expressions without having to run the target in cases -/// where the overhead from copying JIT-compiled code into the target is -/// too high or where the target cannot be run. This class encapsulates -/// a single DWARF location expression or a location list and interprets -/// it. +/// use is to find entities specified in the debug information, since their +/// locations are specified in precisely this language. The second is to +/// interpret expressions without having to run the target in cases where the +/// overhead from copying JIT-compiled code into the target is too high or +/// where the target cannot be run. This class encapsulates a single DWARF +/// location expression or a location list and interprets it. //---------------------------------------------------------------------- class DWARFExpression { public: @@ -130,12 +130,12 @@ public: //------------------------------------------------------------------ /// If a location is not a location list, return true if the location - /// contains a DW_OP_addr () opcode in the stream that matches \a - /// file_addr. If file_addr is LLDB_INVALID_ADDRESS, the this - /// function will return true if the variable there is any DW_OP_addr - /// in a location that (yet still is NOT a location list). This helps - /// us detect if a variable is a global or static variable since - /// there is no other indication from DWARF debug info. + /// contains a DW_OP_addr () opcode in the stream that matches \a file_addr. + /// If file_addr is LLDB_INVALID_ADDRESS, the this function will return true + /// if the variable there is any DW_OP_addr in a location that (yet still is + /// NOT a location list). This helps us detect if a variable is a global or + /// static variable since there is no other indication from DWARF debug + /// info. /// /// @param[in] op_addr_idx /// The DW_OP_addr index to retrieve in case there is more than @@ -161,8 +161,8 @@ public: &link_address_callback); //------------------------------------------------------------------ - /// Make the expression parser read its location information from a - /// given data source. Does not change the offset and length + /// Make the expression parser read its location information from a given + /// data source. Does not change the offset and length /// /// @param[in] data /// A data extractor configured to read the DWARF location expression's @@ -171,8 +171,8 @@ public: void SetOpcodeData(const DataExtractor &data); //------------------------------------------------------------------ - /// Make the expression parser read its location information from a - /// given data source + /// Make the expression parser read its location information from a given + /// data source /// /// @param[in] module_sp /// The module that defines the DWARF expression. @@ -193,16 +193,15 @@ public: //------------------------------------------------------------------ /// Copy the DWARF location expression into a local buffer. /// - /// It is a good idea to copy the data so we don't keep the entire - /// object file worth of data around just for a few bytes of location - /// expression. LLDB typically will mmap the entire contents of debug - /// information files, and if we use SetOpcodeData, it will get a - /// shared reference to all of this data for the and cause the object - /// file to have to stay around. Even worse, a very very large ".a" - /// that contains one or more .o files could end up being referenced. - /// Location lists are typically small so even though we are copying - /// the data, it shouldn't amount to that much for the variables we - /// end up parsing. + /// It is a good idea to copy the data so we don't keep the entire object + /// file worth of data around just for a few bytes of location expression. + /// LLDB typically will mmap the entire contents of debug information files, + /// and if we use SetOpcodeData, it will get a shared reference to all of + /// this data for the and cause the object file to have to stay around. Even + /// worse, a very very large ".a" that contains one or more .o files could + /// end up being referenced. Location lists are typically small so even + /// though we are copying the data, it shouldn't amount to that much for the + /// variables we end up parsing. /// /// @param[in] module_sp /// The module that defines the DWARF expression. @@ -254,8 +253,8 @@ public: //------------------------------------------------------------------ /// Wrapper for the static evaluate function that accepts an - /// ExecutionContextScope instead of an ExecutionContext and uses - /// member variables to populate many operands + /// ExecutionContextScope instead of an ExecutionContext and uses member + /// variables to populate many operands //------------------------------------------------------------------ bool Evaluate(ExecutionContextScope *exe_scope, lldb::addr_t loclist_base_load_addr, @@ -263,8 +262,8 @@ public: Value &result, Status *error_ptr) const; //------------------------------------------------------------------ - /// Wrapper for the static evaluate function that uses member - /// variables to populate many operands + /// Wrapper for the static evaluate function that uses member variables to + /// populate many operands //------------------------------------------------------------------ bool Evaluate(ExecutionContext *exe_ctx, RegisterContext *reg_ctx, lldb::addr_t loclist_base_load_addr, diff --git a/lldb/include/lldb/Expression/Expression.h b/lldb/include/lldb/Expression/Expression.h index 860444e9c2c..6b936386472 100644 --- a/lldb/include/lldb/Expression/Expression.h +++ b/lldb/include/lldb/Expression/Expression.h @@ -28,14 +28,14 @@ namespace lldb_private { class RecordingMemoryManager; //---------------------------------------------------------------------- -/// @class Expression Expression.h "lldb/Expression/Expression.h" -/// @brief Encapsulates a single expression for use in lldb +/// @class Expression Expression.h "lldb/Expression/Expression.h" Encapsulates +/// a single expression for use in lldb /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. Expression encapsulates -/// the objects needed to parse and interpret or JIT an expression. It -/// uses the expression parser appropriate to the language of the expression -/// to produce LLVM IR from the expression. +/// and as a backend for the expr command. Expression encapsulates the +/// objects needed to parse and interpret or JIT an expression. It uses the +/// expression parser appropriate to the language of the expression to produce +/// LLVM IR from the expression. //---------------------------------------------------------------------- class Expression { public: @@ -58,20 +58,19 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ virtual const char *FunctionName() = 0; //------------------------------------------------------------------ - /// Return the language that should be used when parsing. To use - /// the default, return eLanguageTypeUnknown. + /// Return the language that should be used when parsing. To use the + /// default, return eLanguageTypeUnknown. //------------------------------------------------------------------ virtual lldb::LanguageType Language() { return lldb::eLanguageTypeUnknown; } //------------------------------------------------------------------ - /// Return the desired result type of the function, or - /// eResultTypeAny if indifferent. + /// Return the desired result type of the function, or eResultTypeAny if + /// indifferent. //------------------------------------------------------------------ virtual ResultType DesiredResultType() { return eResultTypeAny; } @@ -80,14 +79,12 @@ public: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ virtual bool NeedsValidation() = 0; //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ virtual bool NeedsVariableResolution() = 0; diff --git a/lldb/include/lldb/Expression/ExpressionParser.h b/lldb/include/lldb/Expression/ExpressionParser.h index a550d576f43..66957926650 100644 --- a/lldb/include/lldb/Expression/ExpressionParser.h +++ b/lldb/include/lldb/Expression/ExpressionParser.h @@ -20,8 +20,8 @@ class IRExecutionUnit; //---------------------------------------------------------------------- /// @class ExpressionParser ExpressionParser.h -/// "lldb/Expression/ExpressionParser.h" -/// @brief Encapsulates an instance of a compiler that can parse expressions. +/// "lldb/Expression/ExpressionParser.h" Encapsulates an instance of a +/// compiler that can parse expressions. /// /// ExpressionParser is the base class for llvm based Expression parsers. //---------------------------------------------------------------------- @@ -50,8 +50,8 @@ public: virtual ~ExpressionParser(){}; //------------------------------------------------------------------ - /// Parse a single expression and convert it to IR using Clang. Don't - /// wrap the expression in anything at all. + /// Parse a single expression and convert it to IR using Clang. Don't wrap + /// the expression in anything at all. /// /// @param[in] diagnostic_manager /// The diagnostic manager in which to store the errors and warnings. @@ -64,8 +64,8 @@ public: //------------------------------------------------------------------ /// Try to use the FixIts in the diagnostic_manager to rewrite the - /// expression. If successful, the rewritten expression is stored - /// in the diagnostic_manager, get it out with GetFixedExpression. + /// expression. If successful, the rewritten expression is stored in the + /// diagnostic_manager, get it out with GetFixedExpression. /// /// @param[in] diagnostic_manager /// The diagnostic manager containing fixit's to apply. @@ -78,8 +78,8 @@ public: } //------------------------------------------------------------------ - /// Ready an already-parsed expression for execution, possibly - /// evaluating it statically. + /// Ready an already-parsed expression for execution, possibly evaluating it + /// statically. /// /// @param[out] func_addr /// The address to which the function has been written. diff --git a/lldb/include/lldb/Expression/ExpressionTypeSystemHelper.h b/lldb/include/lldb/Expression/ExpressionTypeSystemHelper.h index 20a5e67cf9b..ffcad54fb9f 100644 --- a/lldb/include/lldb/Expression/ExpressionTypeSystemHelper.h +++ b/lldb/include/lldb/Expression/ExpressionTypeSystemHelper.h @@ -18,11 +18,11 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ExpressionTypeSystemHelper ExpressionTypeSystemHelper.h /// "lldb/Expression/ExpressionTypeSystemHelper.h" -/// @brief A helper object that the Expression can pass to its ExpressionParser +/// A helper object that the Expression can pass to its ExpressionParser /// to provide generic information that /// any type of expression will need to supply. It's only job is to support -/// dyn_cast so that the expression parser -/// can cast it back to the requisite specific type. +/// dyn_cast so that the expression parser can cast it back to the requisite +/// specific type. /// //---------------------------------------------------------------------- diff --git a/lldb/include/lldb/Expression/ExpressionVariable.h b/lldb/include/lldb/Expression/ExpressionVariable.h index 8b5351113ad..89b0500faf9 100644 --- a/lldb/include/lldb/Expression/ExpressionVariable.h +++ b/lldb/include/lldb/Expression/ExpressionVariable.h @@ -126,7 +126,7 @@ public: //---------------------------------------------------------------------- /// @class ExpressionVariableList ExpressionVariable.h /// "lldb/Expression/ExpressionVariable.h" -/// @brief A list of variable references. +/// A list of variable references. /// /// This class stores variables internally, acting as the permanent store. //---------------------------------------------------------------------- diff --git a/lldb/include/lldb/Expression/FunctionCaller.h b/lldb/include/lldb/Expression/FunctionCaller.h index 56305d5181b..c36263e3424 100644 --- a/lldb/include/lldb/Expression/FunctionCaller.h +++ b/lldb/include/lldb/Expression/FunctionCaller.h @@ -29,7 +29,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class FunctionCaller FunctionCaller.h "lldb/Expression/FunctionCaller.h" -/// @brief Encapsulates a function that can be called. +/// Encapsulates a function that can be called. /// /// A given FunctionCaller object can handle a single function signature. /// Once constructed, it can set up any number of concurrent calls to @@ -42,8 +42,8 @@ namespace lldb_private { /// struct with the written arguments. This method lets Clang handle the /// vagaries of function calling conventions. /// -/// The simplest use of the FunctionCaller is to construct it with a -/// function representative of the signature you want to use, then call +/// The simplest use of the FunctionCaller is to construct it with a function +/// representative of the signature you want to use, then call /// ExecuteFunction(ExecutionContext &, Stream &, Value &). /// /// If you need to reuse the arguments for several calls, you can call @@ -53,8 +53,8 @@ namespace lldb_private { /// If you need to call the function on the thread plan stack, you can also /// call InsertFunction() followed by GetThreadPlanToCallFunction(). /// -/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed -/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated +/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a +/// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated /// and its address returned in that variable. /// /// Any of the methods that take arg_addr_ptr can be passed nullptr, and the @@ -170,8 +170,8 @@ public: DiagnosticManager &diagnostic_manager); //------------------------------------------------------------------ - /// Insert an argument struct with a non-default function address and - /// non-default argument values + /// Insert an argument struct with a non-default function address and non- + /// default argument values /// /// @param[in] exe_ctx /// The execution context to insert the function and its arguments @@ -308,28 +308,25 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ const char *FunctionName() override { return m_wrapper_function_name.c_str(); } //------------------------------------------------------------------ - /// Return the object that the parser should use when registering - /// local variables. May be nullptr if the Expression doesn't care. + /// Return the object that the parser should use when registering local + /// variables. May be nullptr if the Expression doesn't care. //------------------------------------------------------------------ ExpressionVariableList *LocalVariables() { return nullptr; } //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ bool NeedsValidation() override { return false; } //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ bool NeedsVariableResolution() override { return false; } diff --git a/lldb/include/lldb/Expression/IRDynamicChecks.h b/lldb/include/lldb/Expression/IRDynamicChecks.h index b793a60585b..f31c03cfb9e 100644 --- a/lldb/include/lldb/Expression/IRDynamicChecks.h +++ b/lldb/include/lldb/Expression/IRDynamicChecks.h @@ -33,17 +33,18 @@ class Stream; //---------------------------------------------------------------------- /// @class DynamicCheckerFunctions IRDynamicChecks.h -/// "lldb/Expression/IRDynamicChecks.h" -/// @brief Encapsulates dynamic check functions used by expressions. +/// "lldb/Expression/IRDynamicChecks.h" Encapsulates dynamic check functions +/// used by expressions. /// /// Each of the utility functions encapsulated in this class is responsible -/// for validating some data that an expression is about to use. Examples are: +/// for validating some data that an expression is about to use. Examples +/// are: /// -/// a = *b; // check that b is a valid pointer -/// [b init]; // check that b is a valid object to send "init" to +/// a = *b; // check that b is a valid pointer [b init]; // check that b +/// is a valid object to send "init" to /// -/// The class installs each checker function into the target process and -/// makes it available to IRDynamicChecks to use. +/// The class installs each checker function into the target process and makes +/// it available to IRDynamicChecks to use. //---------------------------------------------------------------------- class DynamicCheckerFunctions { public: @@ -58,8 +59,8 @@ public: ~DynamicCheckerFunctions(); //------------------------------------------------------------------ - /// Install the utility functions into a process. This binds the - /// instance of DynamicCheckerFunctions to that process. + /// Install the utility functions into a process. This binds the instance + /// of DynamicCheckerFunctions to that process. /// /// @param[in] diagnostic_manager /// A diagnostic manager to report errors to. @@ -81,16 +82,16 @@ public: }; //---------------------------------------------------------------------- -/// @class IRDynamicChecks IRDynamicChecks.h "lldb/Expression/IRDynamicChecks.h" -/// @brief Adds dynamic checks to a user-entered expression to reduce its -/// likelihood of crashing +/// @class IRDynamicChecks IRDynamicChecks.h +/// "lldb/Expression/IRDynamicChecks.h" Adds dynamic checks to a user-entered +/// expression to reduce its likelihood of crashing /// /// When an IR function is executed in the target process, it may cause -/// crashes or hangs by dereferencing NULL pointers, trying to call Objective-C -/// methods on objects that do not respond to them, and so forth. +/// crashes or hangs by dereferencing NULL pointers, trying to call +/// Objective-C methods on objects that do not respond to them, and so forth. /// -/// IRDynamicChecks adds calls to the functions in DynamicCheckerFunctions -/// to appropriate locations in an expression's IR. +/// IRDynamicChecks adds calls to the functions in DynamicCheckerFunctions to +/// appropriate locations in an expression's IR. //---------------------------------------------------------------------- class IRDynamicChecks : public llvm::ModulePass { public: diff --git a/lldb/include/lldb/Expression/IRExecutionUnit.h b/lldb/include/lldb/Expression/IRExecutionUnit.h index 703fcd152af..e73f8956d95 100644 --- a/lldb/include/lldb/Expression/IRExecutionUnit.h +++ b/lldb/include/lldb/Expression/IRExecutionUnit.h @@ -42,23 +42,23 @@ namespace lldb_private { class Status; //---------------------------------------------------------------------- -/// @class IRExecutionUnit IRExecutionUnit.h "lldb/Expression/IRExecutionUnit.h" -/// @brief Contains the IR and, optionally, JIT-compiled code for a module. +/// @class IRExecutionUnit IRExecutionUnit.h +/// "lldb/Expression/IRExecutionUnit.h" Contains the IR and, optionally, JIT- +/// compiled code for a module. /// -/// This class encapsulates the compiled version of an expression, in IR -/// form (for interpretation purposes) and in raw machine code form (for -/// execution in the target). +/// This class encapsulates the compiled version of an expression, in IR form +/// (for interpretation purposes) and in raw machine code form (for execution +/// in the target). /// -/// This object wraps an IR module that comes from the expression parser, -/// and knows how to use the JIT to make it into executable code. It can -/// then be used as input to the IR interpreter, or the address of the -/// executable code can be passed to a thread plan to run in the target. +/// This object wraps an IR module that comes from the expression parser, and +/// knows how to use the JIT to make it into executable code. It can then be +/// used as input to the IR interpreter, or the address of the executable code +/// can be passed to a thread plan to run in the target. /// /// This class creates a subclass of LLVM's SectionMemoryManager, because that -/// is -/// how the JIT emits code. Because LLDB needs to move JIT-compiled code -/// into the target process, the IRExecutionUnit knows how to copy the -/// emitted code into the target process. +/// is how the JIT emits code. Because LLDB needs to move JIT-compiled code +/// into the target process, the IRExecutionUnit knows how to copy the emitted +/// code into the target process. //---------------------------------------------------------------------- class IRExecutionUnit : public std::enable_shared_from_this<IRExecutionUnit>, public IRMemoryMap, @@ -90,9 +90,9 @@ public: lldb::addr_t &func_end); //------------------------------------------------------------------ - /// Accessors for IRForTarget and other clients that may want binary - /// data placed on their behalf. The binary data is owned by the - /// IRExecutionUnit unless the client explicitly chooses to free it. + /// Accessors for IRForTarget and other clients that may want binary data + /// placed on their behalf. The binary data is owned by the IRExecutionUnit + /// unless the client explicitly chooses to free it. //------------------------------------------------------------------ lldb::addr_t WriteNow(const uint8_t *bytes, size_t size, Status &error); @@ -123,7 +123,7 @@ public: //---------------------------------------------------------------------- /// @class JittedFunction IRExecutionUnit.h /// "lldb/Expression/IRExecutionUnit.h" - /// @brief Encapsulates a single function that has been generated by the JIT. + /// Encapsulates a single function that has been generated by the JIT. /// /// Functions that have been generated by the JIT are first resident in the /// local process, and then placed in the target process. JittedFunction @@ -182,9 +182,9 @@ public: private: //------------------------------------------------------------------ - /// Look up the object in m_address_map that contains a given address, - /// find where it was copied to, and return the remote address at the - /// same offset into the copied entity + /// Look up the object in m_address_map that contains a given address, find + /// where it was copied to, and return the remote address at the same offset + /// into the copied entity /// /// @param[in] local_address /// The address in the debugger. @@ -195,9 +195,9 @@ private: lldb::addr_t GetRemoteAddressForLocal(lldb::addr_t local_address); //------------------------------------------------------------------ - /// Look up the object in m_address_map that contains a given address, - /// find where it was copied to, and return its address range in the - /// target process + /// Look up the object in m_address_map that contains a given address, find + /// where it was copied to, and return its address range in the target + /// process /// /// @param[in] local_address /// The address in the debugger. @@ -272,8 +272,8 @@ private: ~MemoryManager() override; //------------------------------------------------------------------ - /// Allocate space for executable code, and add it to the - /// m_spaceBlocks map + /// Allocate space for executable code, and add it to the m_spaceBlocks + /// map /// /// @param[in] Size /// The size of the area. @@ -315,8 +315,8 @@ private: bool IsReadOnly) override; //------------------------------------------------------------------ - /// Called when object loading is complete and section page - /// permissions can be applied. Currently unimplemented for LLDB. + /// Called when object loading is complete and section page permissions + /// can be applied. Currently unimplemented for LLDB. /// /// @param[out] ErrMsg /// The error that prevented the page protection from succeeding. @@ -355,11 +355,11 @@ private: //---------------------------------------------------------------------- /// @class AllocationRecord IRExecutionUnit.h - /// "lldb/Expression/IRExecutionUnit.h" - /// @brief Encapsulates a single allocation request made by the JIT. + /// "lldb/Expression/IRExecutionUnit.h" Encapsulates a single allocation + /// request made by the JIT. /// - /// Allocations made by the JIT are first queued up and then applied in - /// bulk to the underlying process. + /// Allocations made by the JIT are first queued up and then applied in bulk + /// to the underlying process. //---------------------------------------------------------------------- enum class AllocationKind { Stub, Code, Data, Global, Bytes }; diff --git a/lldb/include/lldb/Expression/IRInterpreter.h b/lldb/include/lldb/Expression/IRInterpreter.h index 36e03c6fc4f..2d87346b706 100644 --- a/lldb/include/lldb/Expression/IRInterpreter.h +++ b/lldb/include/lldb/Expression/IRInterpreter.h @@ -29,12 +29,12 @@ class IRMemoryMap; //---------------------------------------------------------------------- /// @class IRInterpreter IRInterpreter.h "lldb/Expression/IRInterpreter.h" -/// @brief Attempt to interpret the function's code if it does not require +/// Attempt to interpret the function's code if it does not require /// running the target. /// -/// In some cases, the IR for an expression can be evaluated entirely -/// in the debugger, manipulating variables but not executing any code -/// in the target. The IRInterpreter attempts to do this. +/// In some cases, the IR for an expression can be evaluated entirely in the +/// debugger, manipulating variables but not executing any code in the target. +/// The IRInterpreter attempts to do this. //---------------------------------------------------------------------- class IRInterpreter { public: diff --git a/lldb/include/lldb/Expression/IRMemoryMap.h b/lldb/include/lldb/Expression/IRMemoryMap.h index ebe297534ca..df8a03f4763 100644 --- a/lldb/include/lldb/Expression/IRMemoryMap.h +++ b/lldb/include/lldb/Expression/IRMemoryMap.h @@ -20,19 +20,19 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class IRMemoryMap IRMemoryMap.h "lldb/Expression/IRMemoryMap.h" -/// @brief Encapsulates memory that may exist in the process but must +/// Encapsulates memory that may exist in the process but must /// also be available in the host process. /// -/// This class encapsulates a group of memory objects that must be readable -/// or writable from the host process regardless of whether the process -/// exists. This allows the IR interpreter as well as JITted code to access -/// the same memory. All allocations made by this class are represented as -/// disjoint intervals. +/// This class encapsulates a group of memory objects that must be readable or +/// writable from the host process regardless of whether the process exists. +/// This allows the IR interpreter as well as JITted code to access the same +/// memory. All allocations made by this class are represented as disjoint +/// intervals. /// /// Point queries against this group of memory objects can be made by the -/// address in the tar at which they reside. If the inferior does not -/// exist, allocations still get made-up addresses. If an inferior appears -/// at some point, then those addresses need to be re-mapped. +/// address in the tar at which they reside. If the inferior does not exist, +/// allocations still get made-up addresses. If an inferior appears at some +/// point, then those addresses need to be re-mapped. //---------------------------------------------------------------------- class IRMemoryMap { public: diff --git a/lldb/include/lldb/Expression/LLVMUserExpression.h b/lldb/include/lldb/Expression/LLVMUserExpression.h index b302bf773f3..a2f87e8a6e2 100644 --- a/lldb/include/lldb/Expression/LLVMUserExpression.h +++ b/lldb/include/lldb/Expression/LLVMUserExpression.h @@ -26,15 +26,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class LLVMUserExpression LLVMUserExpression.h -/// "lldb/Expression/LLVMUserExpression.h" -/// @brief Encapsulates a one-time expression for use in lldb. +/// "lldb/Expression/LLVMUserExpression.h" Encapsulates a one-time expression +/// for use in lldb. /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. LLVMUserExpression is a virtual base -/// class that encapsulates the objects needed to parse and JIT an expression. -/// The actual parsing part will be provided by the specific implementations -/// of LLVMUserExpression - which will be vended through the appropriate -/// TypeSystem. +/// and as a backend for the expr command. LLVMUserExpression is a virtual +/// base class that encapsulates the objects needed to parse and JIT an +/// expression. The actual parsing part will be provided by the specific +/// implementations of LLVMUserExpression - which will be vended through the +/// appropriate TypeSystem. //---------------------------------------------------------------------- class LLVMUserExpression : public UserExpression { public: diff --git a/lldb/include/lldb/Expression/UserExpression.h b/lldb/include/lldb/Expression/UserExpression.h index ced5cb2bf2b..96ca80c882e 100644 --- a/lldb/include/lldb/Expression/UserExpression.h +++ b/lldb/include/lldb/Expression/UserExpression.h @@ -30,7 +30,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class UserExpression UserExpression.h "lldb/Expression/UserExpression.h" -/// @brief Encapsulates a one-time expression for use in lldb. +/// Encapsulates a one-time expression for use in lldb. /// /// LLDB uses expressions for various purposes, notably to call functions /// and as a backend for the expr command. UserExpression is a virtual base @@ -103,8 +103,8 @@ public: bool MatchesContext(ExecutionContext &exe_ctx); //------------------------------------------------------------------ - /// Execute the parsed expression by callinng the derived class's - /// DoExecute method. + /// Execute the parsed expression by callinng the derived class's DoExecute + /// method. /// /// @param[in] diagnostic_manager /// A diagnostic manager to report errors to. @@ -177,32 +177,29 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ const char *FunctionName() override { return "$__lldb_expr"; } //------------------------------------------------------------------ - /// Return the language that should be used when parsing. To use - /// the default, return eLanguageTypeUnknown. + /// Return the language that should be used when parsing. To use the + /// default, return eLanguageTypeUnknown. //------------------------------------------------------------------ lldb::LanguageType Language() override { return m_language; } //------------------------------------------------------------------ - /// Return the desired result type of the function, or - /// eResultTypeAny if indifferent. + /// Return the desired result type of the function, or eResultTypeAny if + /// indifferent. //------------------------------------------------------------------ ResultType DesiredResultType() override { return m_desired_type; } //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ bool NeedsValidation() override { return true; } //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ bool NeedsVariableResolution() override { return true; } @@ -216,8 +213,8 @@ public: virtual lldb::ModuleSP GetJITModule() { return lldb::ModuleSP(); } //------------------------------------------------------------------ - /// Evaluate one expression in the scratch context of the - /// target passed in the exe_ctx and return its result. + /// Evaluate one expression in the scratch context of the target passed in + /// the exe_ctx and return its result. /// /// @param[in] exe_ctx /// The execution context to use when evaluating the expression. diff --git a/lldb/include/lldb/Expression/UtilityFunction.h b/lldb/include/lldb/Expression/UtilityFunction.h index 2187edbc22b..5d4bc8676b9 100644 --- a/lldb/include/lldb/Expression/UtilityFunction.h +++ b/lldb/include/lldb/Expression/UtilityFunction.h @@ -25,13 +25,13 @@ namespace lldb_private { //---------------------------------------------------------------------- -/// @class UtilityFunction UtilityFunction.h "lldb/Expression/UtilityFunction.h" -/// @brief Encapsulates a bit of source code that provides a function that is -/// callable +/// @class UtilityFunction UtilityFunction.h +/// "lldb/Expression/UtilityFunction.h" Encapsulates a bit of source code that +/// provides a function that is callable /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. UtilityFunction encapsulates -/// a self-contained function meant to be used from other code. Utility +/// and as a backend for the expr command. UtilityFunction encapsulates a +/// self-contained function meant to be used from other code. Utility /// functions can perform error-checking for ClangUserExpressions, //---------------------------------------------------------------------- class UtilityFunction : public Expression { @@ -69,8 +69,7 @@ public: /// Check whether the given PC is inside the function /// /// Especially useful if the function dereferences nullptr to indicate a - /// failed - /// assert. + /// failed assert. /// /// @param[in] pc /// The program counter to check. @@ -93,26 +92,23 @@ public: //------------------------------------------------------------------ /// Return the function name that should be used for executing the - /// expression. Text() should contain the definition of this - /// function. + /// expression. Text() should contain the definition of this function. //------------------------------------------------------------------ const char *FunctionName() override { return m_function_name.c_str(); } //------------------------------------------------------------------ - /// Return the object that the parser should use when registering - /// local variables. May be nullptr if the Expression doesn't care. + /// Return the object that the parser should use when registering local + /// variables. May be nullptr if the Expression doesn't care. //------------------------------------------------------------------ ExpressionVariableList *LocalVariables() { return nullptr; } //------------------------------------------------------------------ - /// Return true if validation code should be inserted into the - /// expression. + /// Return true if validation code should be inserted into the expression. //------------------------------------------------------------------ bool NeedsValidation() override { return false; } //------------------------------------------------------------------ - /// Return true if external variables in the expression should be - /// resolved. + /// Return true if external variables in the expression should be resolved. //------------------------------------------------------------------ bool NeedsVariableResolution() override { return false; } diff --git a/lldb/include/lldb/Host/File.h b/lldb/include/lldb/Host/File.h index 1dfa12ea593..d240f810bc8 100644 --- a/lldb/include/lldb/Host/File.h +++ b/lldb/include/lldb/Host/File.h @@ -23,7 +23,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class File File.h "lldb/Host/File.h" -/// @brief A file class. +/// A file class. /// /// A file class that divides abstracts the LLDB core from host file /// functionality. @@ -65,9 +65,9 @@ public: //------------------------------------------------------------------ /// Constructor with path. /// - /// Takes a path to a file which can be just a filename, or a full - /// path. If \a path is not nullptr or empty, this function will call - /// File::Open (const char *path, uint32_t options, uint32_t permissions). + /// Takes a path to a file which can be just a filename, or a full path. If + /// \a path is not nullptr or empty, this function will call File::Open + /// (const char *path, uint32_t options, uint32_t permissions). /// /// @param[in] path /// The full or partial path to a file. @@ -78,7 +78,8 @@ public: /// @param[in] permissions /// Options to use when opening (see File::Permissions) /// - /// @see File::Open (const char *path, uint32_t options, uint32_t permissions) + /// @see File::Open (const char *path, uint32_t options, uint32_t + /// permissions) //------------------------------------------------------------------ File(const char *path, uint32_t options, uint32_t permissions = lldb::eFilePermissionsFileDefault); @@ -87,8 +88,7 @@ public: /// Constructor with FileSpec. /// /// Takes a FileSpec pointing to a file which can be just a filename, or a - /// full - /// path. If \a path is not nullptr or empty, this function will call + /// full path. If \a path is not nullptr or empty, this function will call /// File::Open (const char *path, uint32_t options, uint32_t permissions). /// /// @param[in] filespec @@ -100,7 +100,8 @@ public: /// @param[in] permissions /// Options to use when opening (see File::Permissions) /// - /// @see File::Open (const char *path, uint32_t options, uint32_t permissions) + /// @see File::Open (const char *path, uint32_t options, uint32_t + /// permissions) //------------------------------------------------------------------ File(const FileSpec &filespec, uint32_t options, uint32_t permissions = lldb::eFilePermissionsFileDefault); @@ -125,8 +126,8 @@ public: //------------------------------------------------------------------ /// Convert to pointer operator. /// - /// This allows code to check a File object to see if it - /// contains anything valid using code such as: + /// This allows code to check a File object to see if it contains anything + /// valid using code such as: /// /// @code /// File file(...); @@ -143,8 +144,8 @@ public: //------------------------------------------------------------------ /// Logical NOT operator. /// - /// This allows code to check a File object to see if it is - /// invalid using code such as: + /// This allows code to check a File object to see if it is invalid using + /// code such as: /// /// @code /// File file(...); @@ -169,8 +170,7 @@ public: //------------------------------------------------------------------ /// Open a file for read/writing with the specified options. /// - /// Takes a path to a file which can be just a filename, or a full - /// path. + /// Takes a path to a file which can be just a filename, or a full path. /// /// @param[in] path /// The full or partial path to a file. @@ -202,8 +202,8 @@ public: /// Read bytes from a file from the current file position. /// /// NOTE: This function is NOT thread safe. Use the read function - /// that takes an "off_t &offset" to ensure correct operation in - /// multi-threaded environments. + /// that takes an "off_t &offset" to ensure correct operation in multi- + /// threaded environments. /// /// @param[in] buf /// A buffer where to put the bytes that are read. @@ -222,8 +222,8 @@ public: /// Write bytes to a file at the current file position. /// /// NOTE: This function is NOT thread safe. Use the write function - /// that takes an "off_t &offset" to ensure correct operation in - /// multi-threaded environments. + /// that takes an "off_t &offset" to ensure correct operation in multi- + /// threaded environments. /// /// @param[in] buf /// A buffer where to put the bytes that are read. @@ -243,10 +243,10 @@ public: /// Seek to an offset relative to the beginning of the file. /// /// NOTE: This function is NOT thread safe, other threads that - /// access this object might also change the current file position. - /// For thread safe reads and writes see the following functions: - /// @see File::Read (void *, size_t, off_t &) - /// @see File::Write (const void *, size_t, off_t &) + /// access this object might also change the current file position. For + /// thread safe reads and writes see the following functions: @see + /// File::Read (void *, size_t, off_t &) @see File::Write (const void *, + /// size_t, off_t &) /// /// @param[in] offset /// The offset to seek to within the file relative to the @@ -265,10 +265,10 @@ public: /// Seek to an offset relative to the current file position. /// /// NOTE: This function is NOT thread safe, other threads that - /// access this object might also change the current file position. - /// For thread safe reads and writes see the following functions: - /// @see File::Read (void *, size_t, off_t &) - /// @see File::Write (const void *, size_t, off_t &) + /// access this object might also change the current file position. For + /// thread safe reads and writes see the following functions: @see + /// File::Read (void *, size_t, off_t &) @see File::Write (const void *, + /// size_t, off_t &) /// /// @param[in] offset /// The offset to seek to within the file relative to the @@ -287,10 +287,10 @@ public: /// Seek to an offset relative to the end of the file. /// /// NOTE: This function is NOT thread safe, other threads that - /// access this object might also change the current file position. - /// For thread safe reads and writes see the following functions: - /// @see File::Read (void *, size_t, off_t &) - /// @see File::Write (const void *, size_t, off_t &) + /// access this object might also change the current file position. For + /// thread safe reads and writes see the following functions: @see + /// File::Read (void *, size_t, off_t &) @see File::Write (const void *, + /// size_t, off_t &) /// /// @param[in,out] offset /// The offset to seek to within the file relative to the @@ -310,8 +310,8 @@ public: /// Read bytes from a file from the specified file offset. /// /// NOTE: This function is thread safe in that clients manager their - /// own file position markers and reads on other threads won't mess - /// up the current read. + /// own file position markers and reads on other threads won't mess up the + /// current read. /// /// @param[in] dst /// A buffer where to put the bytes that are read. @@ -335,8 +335,8 @@ public: /// Read bytes from a file from the specified file offset. /// /// NOTE: This function is thread safe in that clients manager their - /// own file position markers and reads on other threads won't mess - /// up the current read. + /// own file position markers and reads on other threads won't mess up the + /// current read. /// /// @param[in,out] num_bytes /// The number of bytes to read form the current file position @@ -367,9 +367,9 @@ public: /// Write bytes to a file at the specified file offset. /// /// NOTE: This function is thread safe in that clients manager their - /// own file position markers, though clients will need to implement - /// their own locking externally to avoid multiple people writing - /// to the file at the same time. + /// own file position markers, though clients will need to implement their + /// own locking externally to avoid multiple people writing to the file at + /// the same time. /// /// @param[in] src /// A buffer containing the bytes to write. @@ -431,10 +431,9 @@ public: //------------------------------------------------------------------ /// Return true if this file from a real terminal. /// - /// Just knowing a file is a interactive isn't enough, we also need - /// to know if the terminal has a width and height so we can do - /// cursor movement and other terminal manipulations by sending - /// escape sequences. + /// Just knowing a file is a interactive isn't enough, we also need to know + /// if the terminal has a width and height so we can do cursor movement and + /// other terminal manipulations by sending escape sequences. /// /// @return /// True if this file is a terminal (tty, not a pty) that has diff --git a/lldb/include/lldb/Host/Host.h b/lldb/include/lldb/Host/Host.h index e0c81848de3..0ff38c404b0 100644 --- a/lldb/include/lldb/Host/Host.h +++ b/lldb/include/lldb/Host/Host.h @@ -56,10 +56,9 @@ inline bool operator!=(WaitStatus a, WaitStatus b) { return !(a == b); } //---------------------------------------------------------------------- /// @class Host Host.h "lldb/Host/Host.h" -/// @brief A class that provides host computer information. +/// A class that provides host computer information. /// -/// Host is a class that answers information about the host operating -/// system. +/// Host is a class that answers information about the host operating system. //---------------------------------------------------------------------- class Host { public: @@ -72,18 +71,17 @@ public: //------------------------------------------------------------------ /// Start monitoring a child process. /// - /// Allows easy monitoring of child processes. \a callback will be - /// called when the child process exits or if it gets a signal. The - /// callback will only be called with signals if \a monitor_signals - /// is \b true. \a callback will usually be called from another - /// thread so the callback function must be thread safe. + /// Allows easy monitoring of child processes. \a callback will be called + /// when the child process exits or if it gets a signal. The callback will + /// only be called with signals if \a monitor_signals is \b true. \a + /// callback will usually be called from another thread so the callback + /// function must be thread safe. /// - /// When the callback gets called, the return value indicates if - /// monitoring should stop. If \b true is returned from \a callback - /// the information will be removed. If \b false is returned then - /// monitoring will continue. If the child process exits, the - /// monitoring will automatically stop after the callback returned - /// regardless of the callback return value. + /// When the callback gets called, the return value indicates if monitoring + /// should stop. If \b true is returned from \a callback the information + /// will be removed. If \b false is returned then monitoring will continue. + /// If the child process exits, the monitoring will automatically stop after + /// the callback returned regardless of the callback return value. /// /// @param[in] callback /// A function callback to call when a child receives a signal @@ -126,9 +124,8 @@ public: static void Kill(lldb::pid_t pid, int signo); //------------------------------------------------------------------ - /// Get the thread token (the one returned by ThreadCreate when the thread was - /// created) for the - /// calling thread in the current process. + /// Get the thread token (the one returned by ThreadCreate when the thread + /// was created) for the calling thread in the current process. /// /// @return /// The thread token for the calling thread in the current process. @@ -138,11 +135,11 @@ public: static const char *GetSignalAsCString(int signo); //------------------------------------------------------------------ - /// Given an address in the current process (the process that - /// is running the LLDB code), return the name of the module that - /// it comes from. This can be useful when you need to know the - /// path to the shared library that your code is running in for - /// loading resources that are relative to your binary. + /// Given an address in the current process (the process that is running the + /// LLDB code), return the name of the module that it comes from. This can + /// be useful when you need to know the path to the shared library that your + /// code is running in for loading resources that are relative to your + /// binary. /// /// @param[in] host_addr /// The pointer to some code in the current process. @@ -155,10 +152,9 @@ public: static FileSpec GetModuleFileSpecForHostAddress(const void *host_addr); //------------------------------------------------------------------ - /// If you have an executable that is in a bundle and want to get - /// back to the bundle directory from the path itself, this - /// function will change a path to a file within a bundle to the - /// bundle directory itself. + /// If you have an executable that is in a bundle and want to get back to + /// the bundle directory from the path itself, this function will change a + /// path to a file within a bundle to the bundle directory itself. /// /// @param[in] file /// A file spec that might point to a file in a bundle. @@ -176,10 +172,9 @@ public: FileSpec &bundle_directory); //------------------------------------------------------------------ - /// When executable files may live within a directory, where the - /// directory represents an executable bundle (like the MacOSX - /// app bundles), then locate the executable within the containing - /// bundle. + /// When executable files may live within a directory, where the directory + /// represents an executable bundle (like the MacOSX app bundles), then + /// locate the executable within the containing bundle. /// /// @param[in,out] file /// A file spec that currently points to the bundle that will @@ -206,8 +201,8 @@ public: static Status LaunchProcess(ProcessLaunchInfo &launch_info); //------------------------------------------------------------------ - /// Perform expansion of the command-line for this launch info - /// This can potentially involve wildcard expansion + /// Perform expansion of the command-line for this launch info This can + /// potentially involve wildcard expansion // environment variable replacement, and whatever other // argument magic the platform defines as part of its typical // user experience @@ -252,8 +247,8 @@ public: namespace llvm { template <> struct format_provider<lldb_private::WaitStatus> { - /// Options = "" gives a human readable description of the status - /// Options = "g" gives a gdb-remote protocol status (e.g., X09) + /// Options = "" gives a human readable description of the status Options = + /// "g" gives a gdb-remote protocol status (e.g., X09) static void format(const lldb_private::WaitStatus &WS, raw_ostream &OS, llvm::StringRef Options); }; diff --git a/lldb/include/lldb/Host/HostInfo.h b/lldb/include/lldb/Host/HostInfo.h index b4a2f8baf37..df762d7160e 100644 --- a/lldb/include/lldb/Host/HostInfo.h +++ b/lldb/include/lldb/Host/HostInfo.h @@ -12,7 +12,7 @@ //---------------------------------------------------------------------- /// @class HostInfo HostInfo.h "lldb/Host/HostInfo.h" -/// @brief A class that provides host computer information. +/// A class that provides host computer information. /// /// HostInfo is a class that answers information about the host operating /// system. Note that HostInfo is NOT intended to be used to manipulate or @@ -22,15 +22,16 @@ /// HostInfoWindows) in a separate file, and then typedefed to HostInfo here. /// Users of the class reference it as HostInfo::method(). /// -/// Not all hosts provide the same functionality. It is important that methods -/// only be implemented at the lowest level at which they make sense. It should -/// be up to the clients of the class to ensure that they not attempt to call a -/// method which doesn't make sense for a particular platform. For example, -/// when implementing a method that only makes sense on a posix-compliant -/// system, implement it on HostInfoPosix, and not on HostInfoBase with a -/// default implementation. This way, users of HostInfo are required to think -/// about the implications of calling a particular method and if used in a -/// context where the method doesn't make sense, will generate a compiler error. +/// Not all hosts provide the same functionality. It is important that +/// methods only be implemented at the lowest level at which they make sense. +/// It should be up to the clients of the class to ensure that they not +/// attempt to call a method which doesn't make sense for a particular +/// platform. For example, when implementing a method that only makes sense +/// on a posix-compliant system, implement it on HostInfoPosix, and not on +/// HostInfoBase with a default implementation. This way, users of HostInfo +/// are required to think about the implications of calling a particular +/// method and if used in a context where the method doesn't make sense, will +/// generate a compiler error. /// //---------------------------------------------------------------------- diff --git a/lldb/include/lldb/Host/HostProcess.h b/lldb/include/lldb/Host/HostProcess.h index dfc997bd81f..626ebab7ce6 100644 --- a/lldb/include/lldb/Host/HostProcess.h +++ b/lldb/include/lldb/Host/HostProcess.h @@ -15,17 +15,17 @@ //---------------------------------------------------------------------- /// @class HostInfo HostInfo.h "lldb/Host/HostProcess.h" -/// @brief A class that represents a running process on the host machine. +/// A class that represents a running process on the host machine. /// /// HostProcess allows querying and manipulation of processes running on the -/// host machine. It is not intended to be represent a process which is -/// being debugged, although the native debug engine of a platform may likely -/// back inferior processes by a HostProcess. +/// host machine. It is not intended to be represent a process which is being +/// debugged, although the native debug engine of a platform may likely back +/// inferior processes by a HostProcess. /// /// HostProcess is implemented using static polymorphism so that on any given -/// platform, an instance of HostProcess will always be able to bind statically -/// to the concrete Process implementation for that platform. See HostInfo -/// for more details. +/// platform, an instance of HostProcess will always be able to bind +/// statically to the concrete Process implementation for that platform. See +/// HostInfo for more details. /// //---------------------------------------------------------------------- diff --git a/lldb/include/lldb/Host/HostThread.h b/lldb/include/lldb/Host/HostThread.h index 0d2fbe6045a..120776283aa 100644 --- a/lldb/include/lldb/Host/HostThread.h +++ b/lldb/include/lldb/Host/HostThread.h @@ -22,7 +22,7 @@ class HostNativeThreadBase; //---------------------------------------------------------------------- /// @class HostInfo HostInfo.h "lldb/Host/HostThread.h" -/// @brief A class that represents a thread running inside of a process on the +/// A class that represents a thread running inside of a process on the /// local machine. /// /// HostThread allows querying and manipulation of threads running on the host diff --git a/lldb/include/lldb/Host/Predicate.h b/lldb/include/lldb/Host/Predicate.h index 15e63d3e63b..d8ab37933eb 100644 --- a/lldb/include/lldb/Host/Predicate.h +++ b/lldb/include/lldb/Host/Predicate.h @@ -38,8 +38,8 @@ typedef enum { //---------------------------------------------------------------------- /// @class Predicate Predicate.h "lldb/Host/Predicate.h" -/// @brief A C++ wrapper class for providing threaded access to a value -/// of type T. +/// A C++ wrapper class for providing threaded access to a value of +/// type T. /// /// A templatized class that provides multi-threaded access to a value /// of type T. Threads can efficiently wait for bits within T to be set diff --git a/lldb/include/lldb/Host/ProcessRunLock.h b/lldb/include/lldb/Host/ProcessRunLock.h index 7044fdbd9ef..6f39eea716e 100644 --- a/lldb/include/lldb/Host/ProcessRunLock.h +++ b/lldb/include/lldb/Host/ProcessRunLock.h @@ -26,9 +26,9 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ProcessRunLock ProcessRunLock.h "lldb/Host/ProcessRunLock.h" -/// @brief A class used to prevent the process from starting while other -/// threads are accessing its data, and prevent access to its data while -/// it is running. +/// A class used to prevent the process from starting while other +/// threads are accessing its data, and prevent access to its data while it is +/// running. //---------------------------------------------------------------------- class ProcessRunLock { diff --git a/lldb/include/lldb/Host/PseudoTerminal.h b/lldb/include/lldb/Host/PseudoTerminal.h index 00c0da6f331..858bd35f73a 100644 --- a/lldb/include/lldb/Host/PseudoTerminal.h +++ b/lldb/include/lldb/Host/PseudoTerminal.h @@ -19,10 +19,10 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class PseudoTerminal PseudoTerminal.h "lldb/Host/PseudoTerminal.h" -/// @brief A pseudo terminal helper class. +/// A pseudo terminal helper class. /// -/// The pseudo terminal class abstracts the use of pseudo terminals on -/// the host system. +/// The pseudo terminal class abstracts the use of pseudo terminals on the +/// host system. //---------------------------------------------------------------------- class PseudoTerminal { public: @@ -33,19 +33,17 @@ public: //------------------------------------------------------------------ /// Default constructor /// - /// Constructs this object with invalid master and slave file - /// descriptors. + /// Constructs this object with invalid master and slave file descriptors. //------------------------------------------------------------------ PseudoTerminal(); //------------------------------------------------------------------ /// Destructor /// - /// The destructor will close the master and slave file descriptors - /// if they are valid and ownership has not been released using - /// one of: - /// @li PseudoTerminal::ReleaseMasterFileDescriptor() - /// @li PseudoTerminal::ReleaseSaveFileDescriptor() + /// The destructor will close the master and slave file descriptors if they + /// are valid and ownership has not been released using one of: @li + /// PseudoTerminal::ReleaseMasterFileDescriptor() @li + /// PseudoTerminal::ReleaseSaveFileDescriptor() //------------------------------------------------------------------ ~PseudoTerminal(); @@ -62,20 +60,18 @@ public: //------------------------------------------------------------------ /// Fork a child process that uses pseudo terminals for its stdio. /// - /// In the parent process, a call to this function results in a pid - /// being returned. If the pid is valid, the master file descriptor - /// can be used for read/write access to stdio of the child process. + /// In the parent process, a call to this function results in a pid being + /// returned. If the pid is valid, the master file descriptor can be used + /// for read/write access to stdio of the child process. /// - /// In the child process the stdin/stdout/stderr will already be - /// routed to the slave pseudo terminal and the master file - /// descriptor will be closed as it is no longer needed by the child - /// process. + /// In the child process the stdin/stdout/stderr will already be routed to + /// the slave pseudo terminal and the master file descriptor will be closed + /// as it is no longer needed by the child process. /// - /// This class will close the file descriptors for the master/slave - /// when the destructor is called. The file handles can be released - /// using either: - /// @li PseudoTerminal::ReleaseMasterFileDescriptor() - /// @li PseudoTerminal::ReleaseSaveFileDescriptor() + /// This class will close the file descriptors for the master/slave when the + /// destructor is called. The file handles can be released using either: @li + /// PseudoTerminal::ReleaseMasterFileDescriptor() @li + /// PseudoTerminal::ReleaseSaveFileDescriptor() /// /// @param[out] error /// An pointer to an error that can describe any errors that @@ -91,10 +87,10 @@ public: //------------------------------------------------------------------ /// The master file descriptor accessor. /// - /// This object retains ownership of the master file descriptor when - /// this accessor is used. Users can call the member function - /// PseudoTerminal::ReleaseMasterFileDescriptor() if this - /// object should release ownership of the slave file descriptor. + /// This object retains ownership of the master file descriptor when this + /// accessor is used. Users can call the member function + /// PseudoTerminal::ReleaseMasterFileDescriptor() if this object should + /// release ownership of the slave file descriptor. /// /// @return /// The master file descriptor, or PseudoTerminal::invalid_fd @@ -107,10 +103,10 @@ public: //------------------------------------------------------------------ /// The slave file descriptor accessor. /// - /// This object retains ownership of the slave file descriptor when - /// this accessor is used. Users can call the member function - /// PseudoTerminal::ReleaseSlaveFileDescriptor() if this - /// object should release ownership of the slave file descriptor. + /// This object retains ownership of the slave file descriptor when this + /// accessor is used. Users can call the member function + /// PseudoTerminal::ReleaseSlaveFileDescriptor() if this object should + /// release ownership of the slave file descriptor. /// /// @return /// The slave file descriptor, or PseudoTerminal::invalid_fd @@ -146,12 +142,12 @@ public: /// Open the first available pseudo terminal. /// /// Opens the first available pseudo terminal with \a oflag as the - /// permissions. The opened master file descriptor is stored in this - /// object and can be accessed by calling the - /// PseudoTerminal::GetMasterFileDescriptor() accessor. Clients - /// can call the PseudoTerminal::ReleaseMasterFileDescriptor() - /// accessor function if they wish to use the master file descriptor - /// beyond the lifespan of this object. + /// permissions. The opened master file descriptor is stored in this object + /// and can be accessed by calling the + /// PseudoTerminal::GetMasterFileDescriptor() accessor. Clients can call the + /// PseudoTerminal::ReleaseMasterFileDescriptor() accessor function if they + /// wish to use the master file descriptor beyond the lifespan of this + /// object. /// /// If this object still has a valid master file descriptor when its /// destructor is called, it will close it. @@ -169,8 +165,8 @@ public: /// successfully opened. /// @li \b false if anything goes wrong. /// - /// @see PseudoTerminal::GetMasterFileDescriptor() - /// @see PseudoTerminal::ReleaseMasterFileDescriptor() + /// @see PseudoTerminal::GetMasterFileDescriptor() @see + /// PseudoTerminal::ReleaseMasterFileDescriptor() //------------------------------------------------------------------ bool OpenFirstAvailableMaster(int oflag, char *error_str, size_t error_len); @@ -178,12 +174,12 @@ public: /// Open the slave for the current master pseudo terminal. /// /// A master pseudo terminal should already be valid prior to - /// calling this function. The opened slave file descriptor is - /// stored in this object and can be accessed by calling the - /// PseudoTerminal::GetSlaveFileDescriptor() accessor. Clients - /// can call the PseudoTerminal::ReleaseSlaveFileDescriptor() - /// accessor function if they wish to use the slave file descriptor - /// beyond the lifespan of this object. + /// calling this function. The opened slave file descriptor is stored in + /// this object and can be accessed by calling the + /// PseudoTerminal::GetSlaveFileDescriptor() accessor. Clients can call the + /// PseudoTerminal::ReleaseSlaveFileDescriptor() accessor function if they + /// wish to use the slave file descriptor beyond the lifespan of this + /// object. /// /// If this object still has a valid slave file descriptor when its /// destructor is called, it will close it. @@ -200,19 +196,19 @@ public: /// successfully opened. /// @li \b false if anything goes wrong. /// - /// @see PseudoTerminal::OpenFirstAvailableMaster() - /// @see PseudoTerminal::GetSlaveFileDescriptor() - /// @see PseudoTerminal::ReleaseSlaveFileDescriptor() + /// @see PseudoTerminal::OpenFirstAvailableMaster() @see + /// PseudoTerminal::GetSlaveFileDescriptor() @see + /// PseudoTerminal::ReleaseSlaveFileDescriptor() //------------------------------------------------------------------ bool OpenSlave(int oflag, char *error_str, size_t error_len); //------------------------------------------------------------------ /// Release the master file descriptor. /// - /// Releases ownership of the master pseudo terminal file descriptor - /// without closing it. The destructor for this class will close the - /// master file descriptor if the ownership isn't released using this - /// call and the master file descriptor has been opened. + /// Releases ownership of the master pseudo terminal file descriptor without + /// closing it. The destructor for this class will close the master file + /// descriptor if the ownership isn't released using this call and the + /// master file descriptor has been opened. /// /// @return /// The master file descriptor, or PseudoTerminal::invalid_fd @@ -223,10 +219,10 @@ public: //------------------------------------------------------------------ /// Release the slave file descriptor. /// - /// Release ownership of the slave pseudo terminal file descriptor - /// without closing it. The destructor for this class will close the - /// slave file descriptor if the ownership isn't released using this - /// call and the slave file descriptor has been opened. + /// Release ownership of the slave pseudo terminal file descriptor without + /// closing it. The destructor for this class will close the slave file + /// descriptor if the ownership isn't released using this call and the slave + /// file descriptor has been opened. /// /// @return /// The slave file descriptor, or PseudoTerminal::invalid_fd diff --git a/lldb/include/lldb/Host/StringConvert.h b/lldb/include/lldb/Host/StringConvert.h index 05bd7808ecd..d197df10d79 100644 --- a/lldb/include/lldb/Host/StringConvert.h +++ b/lldb/include/lldb/Host/StringConvert.h @@ -24,7 +24,7 @@ namespace StringConvert { //---------------------------------------------------------------------- /// @namespace StringConvert StringConvert.h "lldb/Host/StringConvert.h" -/// @brief Utility classes for converting strings into Integers +/// Utility classes for converting strings into Integers //---------------------------------------------------------------------- int32_t ToSInt32(const char *s, int32_t fail_value = 0, int base = 0, diff --git a/lldb/include/lldb/Host/Terminal.h b/lldb/include/lldb/Host/Terminal.h index f0d93ad24ed..193b6d21d51 100644 --- a/lldb/include/lldb/Host/Terminal.h +++ b/lldb/include/lldb/Host/Terminal.h @@ -44,7 +44,7 @@ protected: //---------------------------------------------------------------------- /// @class State Terminal.h "lldb/Host/Terminal.h" -/// @brief A terminal state saving/restoring class. +/// A terminal state saving/restoring class. /// /// This class can be used to remember the terminal state for a file /// descriptor and later restore that state as it originally was. @@ -64,9 +64,9 @@ public: //------------------------------------------------------------------ /// Save the TTY state for \a fd. /// - /// Save the current state of the TTY for the file descriptor "fd" - /// and if "save_process_group" is true, attempt to save the process - /// group info for the TTY. + /// Save the current state of the TTY for the file descriptor "fd" and if + /// "save_process_group" is true, attempt to save the process group info for + /// the TTY. /// /// @param[in] fd /// The file descriptor to save the state of. @@ -84,8 +84,8 @@ public: //------------------------------------------------------------------ /// Restore the TTY state to the cached state. /// - /// Restore the state of the TTY using the cached values from a - /// previous call to TerminalState::Save(int,bool). + /// Restore the state of the TTY using the cached values from a previous + /// call to TerminalState::Save(int,bool). /// /// @return /// Returns \b true if the TTY state was successfully restored, @@ -147,7 +147,7 @@ protected: //---------------------------------------------------------------------- /// @class TerminalStateSwitcher Terminal.h "lldb/Host/Terminal.h" -/// @brief A TTY state switching class. +/// A TTY state switching class. /// /// This class can be used to remember 2 TTY states for a given file /// descriptor and switch between the two states. @@ -182,10 +182,9 @@ public: bool Restore(uint32_t idx) const; //------------------------------------------------------------------ - /// Save the TTY state information for the state at index \a idx. - /// The TTY state is saved for the file descriptor \a fd and - /// the process group information will also be saved if requested - /// by \a save_process_group. + /// Save the TTY state information for the state at index \a idx. The TTY + /// state is saved for the file descriptor \a fd and the process group + /// information will also be saved if requested by \a save_process_group. /// /// @param[in] idx /// The index into the state array where the state should be diff --git a/lldb/include/lldb/Host/posix/PipePosix.h b/lldb/include/lldb/Host/posix/PipePosix.h index 8208b1b8bd6..bb65a56abd0 100644 --- a/lldb/include/lldb/Host/posix/PipePosix.h +++ b/lldb/include/lldb/Host/posix/PipePosix.h @@ -17,7 +17,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class PipePosix PipePosix.h "lldb/Host/posix/PipePosix.h" -/// @brief A posix-based implementation of Pipe, a class that abtracts +/// A posix-based implementation of Pipe, a class that abtracts /// unix style pipes. /// /// A class that abstracts the LLDB core from host pipe functionality. diff --git a/lldb/include/lldb/Host/windows/PipeWindows.h b/lldb/include/lldb/Host/windows/PipeWindows.h index 86dec5a79d8..e309c421a71 100644 --- a/lldb/include/lldb/Host/windows/PipeWindows.h +++ b/lldb/include/lldb/Host/windows/PipeWindows.h @@ -17,7 +17,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Pipe PipeWindows.h "lldb/Host/windows/PipeWindows.h" -/// @brief A windows-based implementation of Pipe, a class that abtracts +/// A windows-based implementation of Pipe, a class that abtracts /// unix style pipes. /// /// A class that abstracts the LLDB core from host pipe functionality. diff --git a/lldb/include/lldb/Interpreter/Options.h b/lldb/include/lldb/Interpreter/Options.h index 62e8b4474ad..ec611cc6c65 100644 --- a/lldb/include/lldb/Interpreter/Options.h +++ b/lldb/include/lldb/Interpreter/Options.h @@ -52,15 +52,13 @@ static inline bool isprint8(int ch) { //---------------------------------------------------------------------- /// @class Options Options.h "lldb/Interpreter/Options.h" -/// @brief A command line option parsing protocol class. +/// A command line option parsing protocol class. /// -/// Options is designed to be subclassed to contain all needed -/// options for a given command. The options can be parsed by calling the Parse -/// function. +/// Options is designed to be subclassed to contain all needed options for a +/// given command. The options can be parsed by calling the Parse function. /// -/// The options are specified using the format defined for the libc -/// options parsing function getopt_long_only: -/// \code +/// The options are specified using the format defined for the libc options +/// parsing function getopt_long_only: \code /// #include <getopt.h> /// int getopt_long_only(int argc, char * const *argv, const char /// *optstring, const struct option *longopts, int *longindex); @@ -124,8 +122,8 @@ public: /// Parse the provided arguments. /// /// The parsed options are set via calls to SetOptionValue. In case of a - /// successful parse, the function returns a copy of the input arguments with - /// the parsed options removed. Otherwise, it returns an error. + /// successful parse, the function returns a copy of the input arguments + /// with the parsed options removed. Otherwise, it returns an error. /// /// param[in] platform_sp /// The platform used for option validation. This is necessary @@ -175,8 +173,8 @@ public: ExecutionContext *execution_context) = 0; //------------------------------------------------------------------ - /// Handles the generic bits of figuring out whether we are in an - /// option, and if so completing it. + /// Handles the generic bits of figuring out whether we are in an option, + /// and if so completing it. /// /// @param[in] input /// The command line parsed into words @@ -203,8 +201,8 @@ public: /// The array of matches returned. /// /// FIXME: This is the wrong return value, since we also need to - /// make a distinction between total number of matches, and the - /// window the user wants returned. + /// make a distinction between total number of matches, and the window the + /// user wants returned. /// /// @return /// \btrue if we were in an option, \bfalse otherwise. @@ -217,8 +215,8 @@ public: lldb_private::StringList &matches); //------------------------------------------------------------------ - /// Handles the generic bits of figuring out whether we are in an - /// option, and if so completing it. + /// Handles the generic bits of figuring out whether we are in an option, + /// and if so completing it. /// /// @param[in] interpreter /// The command interpreter doing the completion. @@ -255,8 +253,8 @@ public: /// The array of matches returned. /// /// FIXME: This is the wrong return value, since we also need to - /// make a distinction between total number of matches, and the - /// window the user wants returned. + /// make a distinction between total number of matches, and the window the + /// user wants returned. /// /// @return /// \btrue if we were in an option, \bfalse otherwise. @@ -343,8 +341,8 @@ public: //---------------------------------------------------------------------- /// Append options from a OptionGroup class. /// - /// Append all options from \a group using the exact same option groups - /// that each option is defined with. + /// Append all options from \a group using the exact same option groups that + /// each option is defined with. /// /// @param[in] group /// A group of options to take option values from and copy their @@ -355,9 +353,9 @@ public: //---------------------------------------------------------------------- /// Append options from a OptionGroup class. /// - /// Append options from \a group that have a usage mask that has any bits - /// in "src_mask" set. After the option definition is copied into the - /// options definitions in this class, set the usage_mask to "dst_mask". + /// Append options from \a group that have a usage mask that has any bits in + /// "src_mask" set. After the option definition is copied into the options + /// definitions in this class, set the usage_mask to "dst_mask". /// /// @param[in] group /// A group of options to take option values from and copy their diff --git a/lldb/include/lldb/Symbol/Block.h b/lldb/include/lldb/Symbol/Block.h index c255b2285b7..1664362431f 100644 --- a/lldb/include/lldb/Symbol/Block.h +++ b/lldb/include/lldb/Symbol/Block.h @@ -30,21 +30,21 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Block Block.h "lldb/Symbol/Block.h" -/// @brief A class that describes a single lexical block. +/// A class that describes a single lexical block. /// /// A Function object owns a BlockList object which owns one or more -/// Block objects. The BlockList object contains a section offset -/// address range, and Block objects contain one or more ranges -/// which are offsets into that range. Blocks are can have discontiguous -/// ranges within the BlockList address range, and each block can -/// contain child blocks each with their own sets of ranges. +/// Block objects. The BlockList object contains a section offset address +/// range, and Block objects contain one or more ranges which are offsets into +/// that range. Blocks are can have discontiguous ranges within the BlockList +/// address range, and each block can contain child blocks each with their own +/// sets of ranges. /// -/// Each block has a variable list that represents local, argument, and -/// static variables that are scoped to the block. +/// Each block has a variable list that represents local, argument, and static +/// variables that are scoped to the block. /// -/// Inlined functions are represented by attaching a -/// InlineFunctionInfo shared pointer object to a block. Inlined -/// functions are represented as named blocks. +/// Inlined functions are represented by attaching a InlineFunctionInfo shared +/// pointer object to a block. Inlined functions are represented as named +/// blocks. //---------------------------------------------------------------------- class Block : public UserID, public SymbolContextScope { public: @@ -54,10 +54,9 @@ public: //------------------------------------------------------------------ /// Construct with a User ID \a uid, \a depth. /// - /// Initialize this block with the specified UID \a uid. The - /// \a depth in the \a block_list is used to represent the parent, - /// sibling, and child block information and also allows for partial - /// parsing at the block level. + /// Initialize this block with the specified UID \a uid. The \a depth in the + /// \a block_list is used to represent the parent, sibling, and child block + /// information and also allows for partial parsing at the block level. /// /// @param[in] uid /// The UID for a given block. This value is given by the @@ -146,8 +145,7 @@ public: bool Contains(const Range &range) const; //------------------------------------------------------------------ - /// Check if this object contains "block" as a child block at any - /// depth. + /// Check if this object contains "block" as a child block at any depth. /// /// @param[in] block /// A potential child block. @@ -256,8 +254,8 @@ public: lldb::VariableListSP GetBlockVariableList(bool can_create); //------------------------------------------------------------------ - /// Get the variable list for this block and optionally all child - /// blocks if \a get_child_variables is \b true. + /// Get the variable list for this block and optionally all child blocks if + /// \a get_child_variables is \b true. /// /// @param[in] get_child_variables /// If \b true, all variables from all child blocks will be @@ -286,8 +284,8 @@ public: VariableList *variable_list); //------------------------------------------------------------------ - /// Appends the variables from this block, and optionally from all - /// parent blocks, to \a variable_list. + /// Appends the variables from this block, and optionally from all parent + /// blocks, to \a variable_list. /// /// @param[in] can_create /// If \b true, the variables can be parsed if they already @@ -334,8 +332,8 @@ public: //------------------------------------------------------------------ /// Get the memory cost of this object. /// - /// Returns the cost of this object plus any owned objects from the - /// ranges, variables, and inline function information. + /// Returns the cost of this object plus any owned objects from the ranges, + /// variables, and inline function information. /// /// @return /// The number of bytes that this object occupies in memory. @@ -374,9 +372,8 @@ public: //------------------------------------------------------------------ /// Set accessor for the variable list. /// - /// Called by the SymbolFile plug-ins after they have parsed the - /// variable lists and are ready to hand ownership of the list over - /// to this object. + /// Called by the SymbolFile plug-ins after they have parsed the variable + /// lists and are ready to hand ownership of the list over to this object. /// /// @param[in] variable_list_sp /// A shared pointer to a VariableList. diff --git a/lldb/include/lldb/Symbol/CompileUnit.h b/lldb/include/lldb/Symbol/CompileUnit.h index e7a1ebc8c00..b816439cee1 100644 --- a/lldb/include/lldb/Symbol/CompileUnit.h +++ b/lldb/include/lldb/Symbol/CompileUnit.h @@ -21,16 +21,16 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class CompileUnit CompileUnit.h "lldb/Symbol/CompileUnit.h" -/// @brief A class that describes a compilation unit. +/// A class that describes a compilation unit. /// /// A representation of a compilation unit, or compiled source file. -/// The UserID of the compile unit is specified by the SymbolFile -/// plug-in and can have any value as long as the value is unique -/// within the Module that owns this compile units. +/// The UserID of the compile unit is specified by the SymbolFile plug-in and +/// can have any value as long as the value is unique within the Module that +/// owns this compile units. /// -/// Each compile unit has a list of functions, global and static -/// variables, support file list (include files and inlined source -/// files), and a line table. +/// Each compile unit has a list of functions, global and static variables, +/// support file list (include files and inlined source files), and a line +/// table. //---------------------------------------------------------------------- class CompileUnit : public std::enable_shared_from_this<CompileUnit>, public ModuleChild, @@ -41,9 +41,9 @@ public: //------------------------------------------------------------------ /// Construct with a module, path, UID and language. /// - /// Initialize the compile unit given the owning \a module, a path - /// to convert into a FileSpec, the SymbolFile plug-in supplied - /// \a uid, and the source language type. + /// Initialize the compile unit given the owning \a module, a path to + /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the + /// source language type. /// /// @param[in] module /// The parent module that owns this compile unit. This value @@ -81,9 +81,9 @@ public: //------------------------------------------------------------------ /// Construct with a module, file spec, UID and language. /// - /// Initialize the compile unit given the owning \a module, a path - /// to convert into a FileSpec, the SymbolFile plug-in supplied - /// \a uid, and the source language type. + /// Initialize the compile unit given the owning \a module, a path to + /// convert into a FileSpec, the SymbolFile plug-in supplied \a uid, and the + /// source language type. /// /// @param[in] module /// The parent module that owns this compile unit. This value @@ -127,8 +127,8 @@ public: //------------------------------------------------------------------ /// Add a function to this compile unit. /// - /// Typically called by the SymbolFile plug-ins as they partially - /// parse the debug information. + /// Typically called by the SymbolFile plug-ins as they partially parse the + /// debug information. /// /// @param[in] function_sp /// A shared pointer to the Function object. @@ -163,13 +163,12 @@ public: void GetDescription(Stream *s, lldb::DescriptionLevel level) const; //------------------------------------------------------------------ - /// Get a shared pointer to a function in this compile unit by - /// index. + /// Get a shared pointer to a function in this compile unit by index. /// - /// Typically called when iterating though all functions in a - /// compile unit after all functions have been parsed. This provides - /// raw access to the function shared pointer list and will not - /// cause the SymbolFile plug-in to parse any unparsed functions. + /// Typically called when iterating though all functions in a compile unit + /// after all functions have been parsed. This provides raw access to the + /// function shared pointer list and will not cause the SymbolFile plug-in + /// to parse any unparsed functions. /// /// @param[in] idx /// An index into the function list. @@ -195,16 +194,15 @@ public: //------------------------------------------------------------------ /// Find the line entry by line and optional inlined file spec. /// - /// Finds the first line entry that has an index greater than - /// \a start_idx that matches \a line. If \a file_spec_ptr - /// is NULL, then the search matches line entries whose file matches - /// the file for the compile unit. If \a file_spec_ptr is - /// not NULL, line entries must match the specified file spec (for - /// inlined line table entries). + /// Finds the first line entry that has an index greater than \a start_idx + /// that matches \a line. If \a file_spec_ptr is NULL, then the search + /// matches line entries whose file matches the file for the compile unit. + /// If \a file_spec_ptr is not NULL, line entries must match the specified + /// file spec (for inlined line table entries). /// - /// Multiple calls to this function can find all entries that match - /// a given file and line by starting with \a start_idx equal to zero, - /// and calling this function back with the return value + 1. + /// Multiple calls to this function can find all entries that match a given + /// file and line by starting with \a start_idx equal to zero, and calling + /// this function back with the return value + 1. /// /// @param[in] start_idx /// The zero based index at which to start looking for matches. @@ -237,10 +235,9 @@ public: //------------------------------------------------------------------ /// Get the line table for the compile unit. /// - /// Called by clients and the SymbolFile plug-in. The SymbolFile - /// plug-ins use this function to determine if the line table has - /// be parsed yet. Clients use this function to get the line table - /// from a compile unit. + /// Called by clients and the SymbolFile plug-in. The SymbolFile plug-ins + /// use this function to determine if the line table has be parsed yet. + /// Clients use this function to get the line table from a compile unit. /// /// @return /// The line table object pointer, or NULL if this line table @@ -253,8 +250,8 @@ public: //------------------------------------------------------------------ /// Get the compile unit's support file list. /// - /// The support file list is used by the line table, and any objects - /// that have valid Declaration objects. + /// The support file list is used by the line table, and any objects that + /// have valid Declaration objects. /// /// @return /// A support file list object. @@ -264,8 +261,8 @@ public: //------------------------------------------------------------------ /// Get the compile unit's imported module list. /// - /// This reports all the imports that the compile unit made, - /// including the current module. + /// This reports all the imports that the compile unit made, including the + /// current module. /// /// @return /// A list of imported module names. @@ -275,9 +272,8 @@ public: //------------------------------------------------------------------ /// Get the SymbolFile plug-in user data. /// - /// SymbolFile plug-ins can store user data to internal state or - /// objects to quickly allow them to parse more information for a - /// given object. + /// SymbolFile plug-ins can store user data to internal state or objects to + /// quickly allow them to parse more information for a given object. /// /// @return /// The user data stored with the CompileUnit when it was @@ -288,9 +284,9 @@ public: //------------------------------------------------------------------ /// Get the variable list for a compile unit. /// - /// Called by clients to get the variable list for a compile unit. - /// The variable list will contain all global and static variables - /// that were defined at the compile unit level. + /// Called by clients to get the variable list for a compile unit. The + /// variable list will contain all global and static variables that were + /// defined at the compile unit level. /// /// @param[in] can_create /// If \b true, the variable list will be parsed on demand. If @@ -309,9 +305,8 @@ public: //------------------------------------------------------------------ /// Finds a function by user ID. /// - /// Typically used by SymbolFile plug-ins when partially parsing - /// the debug information to see if the function has been parsed - /// yet. + /// Typically used by SymbolFile plug-ins when partially parsing the debug + /// information to see if the function has been parsed yet. /// /// @param[in] uid /// The user ID of the function to find. This value is supplied @@ -328,10 +323,9 @@ public: //------------------------------------------------------------------ /// Set the line table for the compile unit. /// - /// Called by the SymbolFile plug-in when if first parses the line - /// table and hands ownership of the line table to this object. The - /// compile unit owns the line table object and will delete the - /// object when it is deleted. + /// Called by the SymbolFile plug-in when if first parses the line table and + /// hands ownership of the line table to this object. The compile unit owns + /// the line table object and will delete the object when it is deleted. /// /// @param[in] line_table /// A line table object pointer that this object now owns. @@ -343,9 +337,8 @@ public: //------------------------------------------------------------------ /// Set accessor for the variable list. /// - /// Called by the SymbolFile plug-ins after they have parsed the - /// variable lists and are ready to hand ownership of the list over - /// to this object. + /// Called by the SymbolFile plug-ins after they have parsed the variable + /// lists and are ready to hand ownership of the list over to this object. /// /// @param[in] variable_list_sp /// A shared pointer to a VariableList. @@ -355,9 +348,8 @@ public: //------------------------------------------------------------------ /// Resolve symbol contexts by file and line. /// - /// Given a file in \a file_spec, and a line number, find all - /// instances and append them to the supplied symbol context list - /// \a sc_list. + /// Given a file in \a file_spec, and a line number, find all instances and + /// append them to the supplied symbol context list \a sc_list. /// /// @param[in] file_spec /// A file specification. If \a file_spec contains no directory @@ -405,10 +397,10 @@ public: //------------------------------------------------------------------ /// Get whether compiler optimizations were enabled for this compile unit /// - /// "optimized" means that the debug experience may be difficult - /// for the user to understand. Variables may not be available when - /// the developer would expect them, stepping through the source lines - /// in the function may appear strange, etc. + /// "optimized" means that the debug experience may be difficult for the + /// user to understand. Variables may not be available when the developer + /// would expect them, stepping through the source lines in the function may + /// appear strange, etc. /// /// @return /// Returns 'true' if this compile unit was compiled with diff --git a/lldb/include/lldb/Symbol/Declaration.h b/lldb/include/lldb/Symbol/Declaration.h index 581176e2396..b654988bccd 100644 --- a/lldb/include/lldb/Symbol/Declaration.h +++ b/lldb/include/lldb/Symbol/Declaration.h @@ -17,13 +17,12 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Declaration Declaration.h "lldb/Symbol/Declaration.h" -/// @brief A class that describes the declaration location of a +/// A class that describes the declaration location of a /// lldb object. /// -/// The declarations include the file specification, line number, and -/// the column info and can help track where functions, blocks, inlined -/// functions, types, variables, any many other debug core objects were -/// declared. +/// The declarations include the file specification, line number, and the +/// column info and can help track where functions, blocks, inlined functions, +/// types, variables, any many other debug core objects were declared. //---------------------------------------------------------------------- class Declaration { public: @@ -92,8 +91,8 @@ public: //------------------------------------------------------------------ /// Clear the object's state. /// - /// Sets the file specification to be empty, and the line and column - /// to zero. + /// Sets the file specification to be empty, and the line and column to + /// zero. //------------------------------------------------------------------ void Clear() { m_file.Clear(); @@ -106,9 +105,9 @@ public: //------------------------------------------------------------------ /// Compare two declaration objects. /// - /// Compares the two file specifications from \a lhs and \a rhs. If - /// the file specifications are equal, then continue to compare the - /// line number and column numbers respectively. + /// Compares the two file specifications from \a lhs and \a rhs. If the file + /// specifications are equal, then continue to compare the line number and + /// column numbers respectively. /// /// @param[in] lhs /// The Left Hand Side const Declaration object reference. @@ -126,8 +125,8 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. /// /// @param[in] s /// The stream to which to dump the object description. diff --git a/lldb/include/lldb/Symbol/Function.h b/lldb/include/lldb/Symbol/Function.h index 9d376007a41..28c6b4857b1 100644 --- a/lldb/include/lldb/Symbol/Function.h +++ b/lldb/include/lldb/Symbol/Function.h @@ -21,10 +21,10 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class FunctionInfo Function.h "lldb/Symbol/Function.h" -/// @brief A class that contains generic function information. +/// A class that contains generic function information. /// -/// This provides generic function information that gets reused between -/// inline functions and function types. +/// This provides generic function information that gets reused between inline +/// functions and function types. //---------------------------------------------------------------------- class FunctionInfo { public: @@ -67,8 +67,8 @@ public: //------------------------------------------------------------------ /// Compare two function information objects. /// - /// First compares the method names, and if equal, then compares - /// the declaration information. + /// First compares the method names, and if equal, then compares the + /// declaration information. /// /// @param[in] lhs /// The Left Hand Side const FunctionInfo object reference. @@ -86,8 +86,8 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -141,13 +141,13 @@ protected: //---------------------------------------------------------------------- /// @class InlineFunctionInfo Function.h "lldb/Symbol/Function.h" -/// @brief A class that describes information for an inlined function. +/// A class that describes information for an inlined function. //---------------------------------------------------------------------- class InlineFunctionInfo : public FunctionInfo { public: //------------------------------------------------------------------ - /// Construct with the function method name, mangled name, and - /// optional declaration information. + /// Construct with the function method name, mangled name, and optional + /// declaration information. /// /// @param[in] name /// A C string name for the method name for this function. This @@ -171,8 +171,8 @@ public: const Declaration *call_decl_ptr); //------------------------------------------------------------------ - /// Construct with the function method name, mangled name, and - /// optional declaration information. + /// Construct with the function method name, mangled name, and optional + /// declaration information. /// /// @param[in] name /// A name for the method name for this function. This value @@ -202,8 +202,8 @@ public: //------------------------------------------------------------------ /// Compare two inlined function information objects. /// - /// First compares the FunctionInfo objects, and if equal, - /// compares the mangled names. + /// First compares the FunctionInfo objects, and if equal, compares the + /// mangled names. /// /// @param[in] lhs /// The Left Hand Side const InlineFunctionInfo object @@ -223,8 +223,8 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -292,17 +292,15 @@ private: //---------------------------------------------------------------------- /// @class Function Function.h "lldb/Symbol/Function.h" -/// @brief A class that describes a function. +/// A class that describes a function. /// -/// Functions belong to CompileUnit objects (Function::m_comp_unit), -/// have unique user IDs (Function::UserID), know how to reconstruct -/// their symbol context (Function::SymbolContextScope), have a -/// specific function type (Function::m_type_uid), have a simple -/// method name (FunctionInfo::m_name), be declared at a specific -/// location (FunctionInfo::m_declaration), possibly have mangled -/// names (Function::m_mangled), an optional return type -/// (Function::m_type), and contains lexical blocks -/// (Function::m_blocks). +/// Functions belong to CompileUnit objects (Function::m_comp_unit), have +/// unique user IDs (Function::UserID), know how to reconstruct their symbol +/// context (Function::SymbolContextScope), have a specific function type +/// (Function::m_type_uid), have a simple method name (FunctionInfo::m_name), +/// be declared at a specific location (FunctionInfo::m_declaration), possibly +/// have mangled names (Function::m_mangled), an optional return type +/// (Function::m_type), and contains lexical blocks (Function::m_blocks). /// /// The function information is split into a few pieces: /// @li The concrete instance information @@ -311,15 +309,14 @@ private: /// The abstract information is found in the function type (Type) that /// describes a function information, return type and parameter types. /// -/// The concrete information is the address range information and -/// specific locations for an instance of this function. +/// The concrete information is the address range information and specific +/// locations for an instance of this function. //---------------------------------------------------------------------- class Function : public UserID, public SymbolContextScope { public: //------------------------------------------------------------------ - /// Construct with a compile unit, function UID, function type UID, - /// optional mangled name, function type, and a section offset - /// based address range. + /// Construct with a compile unit, function UID, function type UID, optional + /// mangled name, function type, and a section offset based address range. /// /// @param[in] comp_unit /// The compile unit to which this function belongs. @@ -352,9 +349,8 @@ public: Type *func_type, const AddressRange &range); //------------------------------------------------------------------ - /// Construct with a compile unit, function UID, function type UID, - /// optional mangled name, function type, and a section offset - /// based address range. + /// Construct with a compile unit, function UID, function type UID, optional + /// mangled name, function type, and a section offset based address range. /// /// @param[in] comp_unit /// The compile unit to which this function belongs. @@ -408,10 +404,10 @@ public: lldb::LanguageType GetLanguage() const; //------------------------------------------------------------------ - /// Find the file and line number of the source location of the start - /// of the function. This will use the declaration if present and fall - /// back on the line table if that fails. So there may NOT be a line - /// table entry for this source file/line combo. + /// Find the file and line number of the source location of the start of the + /// function. This will use the declaration if present and fall back on the + /// line table if that fails. So there may NOT be a line table entry for + /// this source file/line combo. /// /// @param[out] source_file /// The source file. @@ -422,8 +418,8 @@ public: void GetStartLineSourceInfo(FileSpec &source_file, uint32_t &line_no); //------------------------------------------------------------------ - /// Find the file and line number of the source location of the end - /// of the function. + /// Find the file and line number of the source location of the end of the + /// function. /// /// /// @param[out] source_file @@ -497,8 +493,8 @@ public: CompilerDeclContext GetDeclContext(); //------------------------------------------------------------------ - /// Get accessor for the type that describes the function - /// return value type, and parameter types. + /// Get accessor for the type that describes the function return value type, + /// and parameter types. /// /// @return /// A type object pointer. @@ -506,8 +502,8 @@ public: Type *GetType(); //------------------------------------------------------------------ - /// Get const accessor for the type that describes the function - /// return value type, and parameter types. + /// Get const accessor for the type that describes the function return value + /// type, and parameter types. /// /// @return /// A const type object pointer. @@ -518,10 +514,8 @@ public: //------------------------------------------------------------------ /// Get the size of the prologue instructions for this function. The - /// "prologue" - /// instructions include any instructions given line number 0 immediately - /// following - /// the prologue end. + /// "prologue" instructions include any instructions given line number 0 + /// immediately following the prologue end. /// /// @return /// The size of the prologue. @@ -531,8 +525,8 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -567,10 +561,10 @@ public: /// /// The debug information may provide information about whether this /// function was compiled with optimization or not. In this case, - /// "optimized" means that the debug experience may be difficult - /// for the user to understand. Variables may not be available when - /// the developer would expect them, stepping through the source lines - /// in the function may appear strange, etc. + /// "optimized" means that the debug experience may be difficult for the + /// user to understand. Variables may not be available when the developer + /// would expect them, stepping through the source lines in the function may + /// appear strange, etc. /// /// @return /// Returns 'true' if this function was compiled with @@ -582,10 +576,10 @@ public: //------------------------------------------------------------------ /// Get whether this function represents a 'top-level' function /// - /// The concept of a top-level function is language-specific, mostly - /// meant to represent the notion of scripting-style code that has - /// global visibility of the variables/symbols/functions/... - /// defined within the containing file/module + /// The concept of a top-level function is language-specific, mostly meant + /// to represent the notion of scripting-style code that has global + /// visibility of the variables/symbols/functions/... defined within the + /// containing file/module /// /// If stopped in a top-level function, LLDB will expose global variables /// as-if locals in the 'frame variable' command diff --git a/lldb/include/lldb/Symbol/LineEntry.h b/lldb/include/lldb/Symbol/LineEntry.h index b9a1a1442d4..c1ce614609c 100644 --- a/lldb/include/lldb/Symbol/LineEntry.h +++ b/lldb/include/lldb/Symbol/LineEntry.h @@ -18,7 +18,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class LineEntry LineEntry.h "lldb/Symbol/LineEntry.h" -/// @brief A line table entry class. +/// A line table entry class. //---------------------------------------------------------------------- struct LineEntry { //------------------------------------------------------------------ @@ -44,8 +44,8 @@ struct LineEntry { //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -79,8 +79,8 @@ struct LineEntry { Target *target, bool show_address_only) const; //------------------------------------------------------------------ - /// Dumps information specific to a process that stops at this - /// line entry to the supplied stream \a s. + /// Dumps information specific to a process that stops at this line entry to + /// the supplied stream \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -123,25 +123,25 @@ struct LineEntry { static int Compare(const LineEntry &lhs, const LineEntry &rhs); //------------------------------------------------------------------ - /// Give the range for this LineEntry + any additional LineEntries for - /// this same source line that are contiguous. + /// Give the range for this LineEntry + any additional LineEntries for this + /// same source line that are contiguous. /// /// A compiler may emit multiple line entries for a single source line, - /// e.g. to indicate subexpressions at different columns. This method - /// will get the AddressRange for all of the LineEntries for this source - /// line that are contiguous. + /// e.g. to indicate subexpressions at different columns. This method will + /// get the AddressRange for all of the LineEntries for this source line + /// that are contiguous. // - /// Line entries with a line number of 0 are treated specially - these - /// are compiler-generated line table entries that the user did not - /// write in their source code, and we want to skip past in the debugger. - /// If this LineEntry is for line 32, and the following LineEntry is for - /// line 0, we will extend the range to include the AddressRange of the - /// line 0 LineEntry (and it will include the range of the following - /// LineEntries that match either 32 or 0.) - /// - /// If the initial LineEntry this method is called on is a line #0, only - /// the range of contiuous LineEntries with line #0 will be included in - /// the complete range. + /// Line entries with a line number of 0 are treated specially - these are + /// compiler-generated line table entries that the user did not write in + /// their source code, and we want to skip past in the debugger. If this + /// LineEntry is for line 32, and the following LineEntry is for line 0, we + /// will extend the range to include the AddressRange of the line 0 + /// LineEntry (and it will include the range of the following LineEntries + /// that match either 32 or 0.) + /// + /// If the initial LineEntry this method is called on is a line #0, only the + /// range of contiuous LineEntries with line #0 will be included in the + /// complete range. /// /// @return /// The contiguous AddressRange for this source line. diff --git a/lldb/include/lldb/Symbol/LineTable.h b/lldb/include/lldb/Symbol/LineTable.h index a55e797f7b1..fe8be0c5576 100644 --- a/lldb/include/lldb/Symbol/LineTable.h +++ b/lldb/include/lldb/Symbol/LineTable.h @@ -25,8 +25,8 @@ namespace lldb_private { //---------------------------------------------------------------------- -/// @class LineSequence LineTable.h "lldb/Symbol/LineTable.h" -/// @brief An abstract base class used during symbol table creation. +/// @class LineSequence LineTable.h "lldb/Symbol/LineTable.h" An abstract base +/// class used during symbol table creation. //---------------------------------------------------------------------- class LineSequence { public: @@ -42,7 +42,7 @@ private: //---------------------------------------------------------------------- /// @class LineTable LineTable.h "lldb/Symbol/LineTable.h" -/// @brief A line table class. +/// A line table class. //---------------------------------------------------------------------- class LineTable { public: @@ -111,8 +111,7 @@ public: void GetDescription(Stream *s, Target *target, lldb::DescriptionLevel level); //------------------------------------------------------------------ - /// Find a line entry that contains the section offset address \a - /// so_addr. + /// Find a line entry that contains the section offset address \a so_addr. /// /// @param[in] so_addr /// A section offset address object containing the address we @@ -134,12 +133,12 @@ public: uint32_t *index_ptr = nullptr); //------------------------------------------------------------------ - /// Find a line entry index that has a matching file index and - /// source line number. + /// Find a line entry index that has a matching file index and source line + /// number. /// - /// Finds the next line entry that has a matching \a file_idx and - /// source line number \a line starting at the \a start_idx entries - /// into the line entry collection. + /// Finds the next line entry that has a matching \a file_idx and source + /// line number \a line starting at the \a start_idx entries into the line + /// entry collection. /// /// @param[in] start_idx /// The number of entries to skip when starting the search. @@ -224,8 +223,8 @@ public: bool append); //------------------------------------------------------------------ - /// Given a file range link map, relink the current line table - /// and return a fixed up line table. + /// Given a file range link map, relink the current line table and return a + /// fixed up line table. /// /// @param[out] file_range_map /// A collection of file ranges that maps to new file ranges diff --git a/lldb/include/lldb/Symbol/ObjectContainer.h b/lldb/include/lldb/Symbol/ObjectContainer.h index 110379234fb..2138d22808c 100644 --- a/lldb/include/lldb/Symbol/ObjectContainer.h +++ b/lldb/include/lldb/Symbol/ObjectContainer.h @@ -25,23 +25,23 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ObjectContainer ObjectContainer.h "lldb/Symbol/ObjectContainer.h" -/// @brief A plug-in interface definition class for object containers. +/// A plug-in interface definition class for object containers. /// -/// Object containers contain object files from one or more -/// architectures, and also can contain one or more named objects. +/// Object containers contain object files from one or more architectures, and +/// also can contain one or more named objects. /// -/// Typical object containers are static libraries (.a files) that -/// contain multiple named object files, and universal files that contain -/// multiple architectures. +/// Typical object containers are static libraries (.a files) that contain +/// multiple named object files, and universal files that contain multiple +/// architectures. //---------------------------------------------------------------------- class ObjectContainer : public PluginInterface, public ModuleChild { public: //------------------------------------------------------------------ /// Construct with a parent module, offset, and header data. /// - /// Object files belong to modules and a valid module must be - /// supplied upon construction. The at an offset within a file for - /// objects that contain more than one architecture or object. + /// Object files belong to modules and a valid module must be supplied upon + /// construction. The at an offset within a file for objects that contain + /// more than one architecture or object. //------------------------------------------------------------------ ObjectContainer(const lldb::ModuleSP &module_sp, const FileSpec *file, lldb::offset_t file_offset, lldb::offset_t length, @@ -58,18 +58,17 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited from by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// from by the plug-in instance. //------------------------------------------------------------------ ~ObjectContainer() override = default; //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the current contents of this object - /// to the supplied stream \a s. The dumping should include the - /// section list if it has been parsed, and the symbol table - /// if it has been parsed. + /// Dump a description of the current contents of this object to the + /// supplied stream \a s. The dumping should include the section list if it + /// has been parsed, and the symbol table if it has been parsed. /// /// @param[in] s /// The stream to which to dump the object description. @@ -101,8 +100,8 @@ public: //------------------------------------------------------------------ /// Returns the offset into a file at which this object resides. /// - /// Some files contain many object files, and this function allows - /// access to an object's offset within the file. + /// Some files contain many object files, and this function allows access to + /// an object's offset within the file. /// /// @return /// The offset in bytes into the file. Defaults to zero for @@ -124,10 +123,10 @@ public: //------------------------------------------------------------------ /// Get the number of architectures in this object file. /// - /// The default implementation returns 1 as for object files that - /// contain a single architecture. ObjectContainer instances that - /// contain more than one architecture should override this function - /// and return an appropriate value. + /// The default implementation returns 1 as for object files that contain a + /// single architecture. ObjectContainer instances that contain more than + /// one architecture should override this function and return an appropriate + /// value. /// /// @return /// The number of architectures contained in this object file. @@ -137,11 +136,11 @@ public: //------------------------------------------------------------------ /// Attempts to parse the object header. /// - /// This function is used as a test to see if a given plug-in - /// instance can parse the header data already contained in - /// ObjectContainer::m_data. If an object file parser does not - /// recognize that magic bytes in a header, false should be returned - /// and the next plug-in can attempt to parse an object file. + /// This function is used as a test to see if a given plug-in instance can + /// parse the header data already contained in ObjectContainer::m_data. If + /// an object file parser does not recognize that magic bytes in a header, + /// false should be returned and the next plug-in can attempt to parse an + /// object file. /// /// @return /// Returns \b true if the header was parsed successfully, \b @@ -152,14 +151,14 @@ public: //------------------------------------------------------------------ /// Selects an architecture in an object file. /// - /// Object files that contain a single architecture should verify - /// that the specified \a arch matches the architecture in in - /// object file and return \b true or \b false accordingly. + /// Object files that contain a single architecture should verify that the + /// specified \a arch matches the architecture in in object file and return + /// \b true or \b false accordingly. /// - /// Object files that contain more than one architecture should - /// attempt to select that architecture, and if successful, clear - /// out any previous state from any previously selected architecture - /// and prepare to return information for the new architecture. + /// Object files that contain more than one architecture should attempt to + /// select that architecture, and if successful, clear out any previous + /// state from any previously selected architecture and prepare to return + /// information for the new architecture. /// /// @return /// Returns a pointer to the object file of the requested \a diff --git a/lldb/include/lldb/Symbol/ObjectFile.h b/lldb/include/lldb/Symbol/ObjectFile.h index 8946f5a0c18..21600d6801f 100644 --- a/lldb/include/lldb/Symbol/ObjectFile.h +++ b/lldb/include/lldb/Symbol/ObjectFile.h @@ -44,16 +44,15 @@ public: //---------------------------------------------------------------------- /// @class ObjectFile ObjectFile.h "lldb/Symbol/ObjectFile.h" -/// @brief A plug-in interface definition class for object file parsers. +/// A plug-in interface definition class for object file parsers. /// -/// Object files belong to Module objects and know how to extract -/// information from executable, shared library, and object (.o) files -/// used by operating system runtime. The symbol table and section list -/// for an object file. +/// Object files belong to Module objects and know how to extract information +/// from executable, shared library, and object (.o) files used by operating +/// system runtime. The symbol table and section list for an object file. /// -/// Object files can be represented by the entire file, or by part of a -/// file. An example of a partial file ObjectFile is one that contains -/// information for one of multiple architectures in the same file. +/// Object files can be represented by the entire file, or by part of a file. +/// An example of a partial file ObjectFile is one that contains information +/// for one of multiple architectures in the same file. /// /// Once an architecture is selected the object file information can be /// extracted from this abstract class. @@ -96,9 +95,9 @@ public: //------------------------------------------------------------------ /// Construct with a parent module, offset, and header data. /// - /// Object files belong to modules and a valid module must be - /// supplied upon construction. The at an offset within a file for - /// objects that contain more than one architecture or object. + /// Object files belong to modules and a valid module must be supplied upon + /// construction. The at an offset within a file for objects that contain + /// more than one architecture or object. //------------------------------------------------------------------ ObjectFile(const lldb::ModuleSP &module_sp, const FileSpec *file_spec_ptr, lldb::offset_t file_offset, lldb::offset_t length, @@ -110,18 +109,17 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited from by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// from by the plug-in instance. //------------------------------------------------------------------ ~ObjectFile() override; //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the current contents of this object - /// to the supplied stream \a s. The dumping should include the - /// section list if it has been parsed, and the symbol table - /// if it has been parsed. + /// Dump a description of the current contents of this object to the + /// supplied stream \a s. The dumping should include the section list if it + /// has been parsed, and the symbol table if it has been parsed. /// /// @param[in] s /// The stream to which to dump the object description. @@ -131,9 +129,9 @@ public: //------------------------------------------------------------------ /// Find a ObjectFile plug-in that can parse \a file_spec. /// - /// Scans all loaded plug-in interfaces that implement versions of - /// the ObjectFile plug-in interface and returns the first - /// instance that can parse the file. + /// Scans all loaded plug-in interfaces that implement versions of the + /// ObjectFile plug-in interface and returns the first instance that can + /// parse the file. /// /// @param[in] module /// The parent module that owns this object file. @@ -161,9 +159,9 @@ public: //------------------------------------------------------------------ /// Find a ObjectFile plug-in that can parse a file in memory. /// - /// Scans all loaded plug-in interfaces that implement versions of - /// the ObjectFile plug-in interface and returns the first - /// instance that can parse the file. + /// Scans all loaded plug-in interfaces that implement versions of the + /// ObjectFile plug-in interface and returns the first instance that can + /// parse the file. /// /// @param[in] module /// The parent module that owns this object file. @@ -194,9 +192,9 @@ public: //------------------------------------------------------------------ /// Split a path into a file path with object name. /// - /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path - /// up into the actual path name and into the object name so we can - /// make a valid object file from it. + /// For paths like "/tmp/foo.a(bar.o)" we often need to split a path up into + /// the actual path name and into the object name so we can make a valid + /// object file from it. /// /// @param[in] path_with_object /// A path that might contain an archive path with a .o file @@ -233,13 +231,11 @@ public: //------------------------------------------------------------------ /// Get the address type given a file address in an object file. /// - /// Many binary file formats know what kinds - /// This is primarily for ARM binaries, though it can be applied to - /// any executable file format that supports different opcode types - /// within the same binary. ARM binaries support having both ARM and - /// Thumb within the same executable container. We need to be able - /// to get - /// @return + /// Many binary file formats know what kinds This is primarily for ARM + /// binaries, though it can be applied to any executable file format that + /// supports different opcode types within the same binary. ARM binaries + /// support having both ARM and Thumb within the same executable container. + /// We need to be able to get @return /// The size of an address in bytes for the currently selected /// architecture (and object for archives). Returns zero if no /// architecture or object has been selected. @@ -249,13 +245,11 @@ public: //------------------------------------------------------------------ /// Extract the dependent modules from an object file. /// - /// If an object file has information about which other images it - /// depends on (such as shared libraries), this function will - /// provide the list. Since many executables or shared libraries - /// may depend on the same files, - /// FileSpecList::AppendIfUnique(const FileSpec &) should be - /// used to make sure any files that are added are not already in - /// the list. + /// If an object file has information about which other images it depends on + /// (such as shared libraries), this function will provide the list. Since + /// many executables or shared libraries may depend on the same files, + /// FileSpecList::AppendIfUnique(const FileSpec &) should be used to make + /// sure any files that are added are not already in the list. /// /// @param[out] file_list /// A list of file specification objects that gets dependent @@ -280,8 +274,8 @@ public: //------------------------------------------------------------------ /// Returns the offset into a file at which this object resides. /// - /// Some files contain many object files, and this function allows - /// access to an object's offset within the file. + /// Some files contain many object files, and this function allows access to + /// an object's offset within the file. /// /// @return /// The offset in bytes into the file. Defaults to zero for @@ -312,8 +306,8 @@ public: //------------------------------------------------------------------ /// Get the name of the cpu, vendor and OS for this object file. /// - /// This value is a string that represents the target triple where - /// the cpu type, the vendor and the OS are encoded into a string. + /// This value is a string that represents the target triple where the cpu + /// type, the vendor and the OS are encoded into a string. /// /// @param[out] target_triple /// The string value of the target triple. @@ -325,11 +319,11 @@ public: virtual bool GetArchitecture(ArchSpec &arch) = 0; //------------------------------------------------------------------ - /// Gets the section list for the currently selected architecture - /// (and object for archives). + /// Gets the section list for the currently selected architecture (and + /// object for archives). /// - /// Section list parsing can be deferred by ObjectFile instances - /// until this accessor is called the first time. + /// Section list parsing can be deferred by ObjectFile instances until this + /// accessor is called the first time. /// /// @return /// The list of sections contained in this object file. @@ -339,17 +333,17 @@ public: virtual void CreateSections(SectionList &unified_section_list) = 0; //------------------------------------------------------------------ - /// Notify the ObjectFile that the file addresses in the Sections - /// for this module have been changed. + /// Notify the ObjectFile that the file addresses in the Sections for this + /// module have been changed. //------------------------------------------------------------------ virtual void SectionFileAddressesChanged() {} //------------------------------------------------------------------ - /// Gets the symbol table for the currently selected architecture - /// (and object for archives). + /// Gets the symbol table for the currently selected architecture (and + /// object for archives). /// - /// Symbol table parsing can be deferred by ObjectFile instances - /// until this accessor is called the first time. + /// Symbol table parsing can be deferred by ObjectFile instances until this + /// accessor is called the first time. /// /// @return /// The symbol table for this object file. @@ -365,11 +359,11 @@ public: //------------------------------------------------------------------ /// Appends a Symbol for the specified so_addr to the symbol table. /// - /// If verify_unique is false, the symbol table is not searched - /// to determine if a Symbol found at this address has already been - /// added to the symbol table. When verify_unique is true, this - /// method resolves the Symbol as the first match in the SymbolTable - /// and appends a Symbol only if required/found. + /// If verify_unique is false, the symbol table is not searched to determine + /// if a Symbol found at this address has already been added to the symbol + /// table. When verify_unique is true, this method resolves the Symbol as + /// the first match in the SymbolTable and appends a Symbol only if + /// required/found. /// /// @return /// The resolved symbol or nullptr. Returns nullptr if a @@ -415,10 +409,9 @@ public: //------------------------------------------------------------------ /// Gets the UUID for this object file. /// - /// If the object file format contains a UUID, the value should be - /// returned. Else ObjectFile instances should return the MD5 - /// checksum of all of the bytes for the object file (or memory for - /// memory based object files). + /// If the object file format contains a UUID, the value should be returned. + /// Else ObjectFile instances should return the MD5 checksum of all of the + /// bytes for the object file (or memory for memory based object files). /// /// @return /// Returns \b true if a UUID was successfully extracted into @@ -429,8 +422,8 @@ public: //------------------------------------------------------------------ /// Gets the symbol file spec list for this object file. /// - /// If the object file format contains a debug symbol file link, - /// the values will be returned in the FileSpecList. + /// If the object file format contains a debug symbol file link, the values + /// will be returned in the FileSpecList. /// /// @return /// Returns filespeclist. @@ -443,8 +436,8 @@ public: /// Gets the file spec list of libraries re-exported by this object file. /// /// If the object file format has the notion of one library re-exporting the - /// symbols from another, - /// the re-exported libraries will be returned in the FileSpecList. + /// symbols from another, the re-exported libraries will be returned in the + /// FileSpecList. /// /// @return /// Returns filespeclist. @@ -454,8 +447,8 @@ public: } //------------------------------------------------------------------ - /// Sets the load address for an entire module, assuming a rigid - /// slide of sections, if possible in the implementation. + /// Sets the load address for an entire module, assuming a rigid slide of + /// sections, if possible in the implementation. /// /// @return /// Returns true iff any section's load address changed. @@ -466,8 +459,8 @@ public: } //------------------------------------------------------------------ - /// Gets whether endian swapping should occur when extracting data - /// from this object file. + /// Gets whether endian swapping should occur when extracting data from this + /// object file. /// /// @return /// Returns \b true if endian swapping is needed, \b false @@ -478,11 +471,11 @@ public: //------------------------------------------------------------------ /// Attempts to parse the object header. /// - /// This function is used as a test to see if a given plug-in - /// instance can parse the header data already contained in - /// ObjectFile::m_data. If an object file parser does not - /// recognize that magic bytes in a header, false should be returned - /// and the next plug-in can attempt to parse an object file. + /// This function is used as a test to see if a given plug-in instance can + /// parse the header data already contained in ObjectFile::m_data. If an + /// object file parser does not recognize that magic bytes in a header, + /// false should be returned and the next plug-in can attempt to parse an + /// object file. /// /// @return /// Returns \b true if the header was parsed successfully, \b @@ -493,11 +486,11 @@ public: //------------------------------------------------------------------ /// Returns a reference to the UnwindTable for this ObjectFile /// - /// The UnwindTable contains FuncUnwinders objects for any function in - /// this ObjectFile. If a FuncUnwinders object hasn't been created yet - /// (i.e. the function has yet to be unwound in a stack walk), it - /// will be created when requested. Specifically, we do not create - /// FuncUnwinders objects for functions until they are needed. + /// The UnwindTable contains FuncUnwinders objects for any function in this + /// ObjectFile. If a FuncUnwinders object hasn't been created yet (i.e. the + /// function has yet to be unwound in a stack walk), it will be created when + /// requested. Specifically, we do not create FuncUnwinders objects for + /// functions until they are needed. /// /// @return /// Returns the unwind table for this object file. @@ -505,21 +498,21 @@ public: virtual lldb_private::UnwindTable &GetUnwindTable() { return m_unwind_table; } //------------------------------------------------------------------ - /// Returns if the function bounds for symbols in this symbol file - /// are likely accurate. + /// Returns if the function bounds for symbols in this symbol file are + /// likely accurate. /// /// The unwinder can emulate the instructions of functions to understand - /// prologue/epilogue code sequences, where registers are spilled on - /// the stack, etc. This feature relies on having the correct start - /// addresses of all functions. If the ObjectFile has a way to tell - /// that symbols have been stripped and there's no way to reconstruct - /// start addresses (e.g. LC_FUNCTION_STARTS on Mach-O, or eh_frame - /// unwind info), the ObjectFile should indicate that assembly emulation - /// should not be used for this module. + /// prologue/epilogue code sequences, where registers are spilled on the + /// stack, etc. This feature relies on having the correct start addresses + /// of all functions. If the ObjectFile has a way to tell that symbols have + /// been stripped and there's no way to reconstruct start addresses (e.g. + /// LC_FUNCTION_STARTS on Mach-O, or eh_frame unwind info), the ObjectFile + /// should indicate that assembly emulation should not be used for this + /// module. /// - /// It is uncommon for this to return false. An ObjectFile needs to - /// be sure that symbol start addresses are unavailable before false - /// is returned. If it is unclear, this should return true. + /// It is uncommon for this to return false. An ObjectFile needs to be sure + /// that symbol start addresses are unavailable before false is returned. + /// If it is unclear, this should return true. /// /// @return /// Returns true if assembly emulation should be used for this @@ -547,9 +540,9 @@ public: } //------------------------------------------------------------------ - /// Returns the address of the Entry Point in this object file - if - /// the object file doesn't have an entry point (because it is not an - /// executable file) then an invalid address is returned. + /// Returns the address of the Entry Point in this object file - if the + /// object file doesn't have an entry point (because it is not an executable + /// file) then an invalid address is returned. /// /// @return /// Returns the entry address for this module. @@ -557,14 +550,13 @@ public: virtual lldb_private::Address GetEntryPointAddress() { return Address(); } //------------------------------------------------------------------ - /// Returns the address that represents the header of this object - /// file. + /// Returns the address that represents the header of this object file. /// - /// The header address is defined as where the header for the object - /// file is that describes the content of the file. If the header - /// doesn't appear in a section that is defined in the object file, - /// an address with no section is returned that has the file offset - /// set in the m_file_offset member of the lldb_private::Address object. + /// The header address is defined as where the header for the object file is + /// that describes the content of the file. If the header doesn't appear in + /// a section that is defined in the object file, an address with no section + /// is returned that has the file offset set in the m_file_offset member of + /// the lldb_private::Address object. /// /// @return /// Returns the entry address for this module. @@ -576,9 +568,9 @@ public: virtual uint32_t GetNumThreadContexts() { return 0; } //------------------------------------------------------------------ - /// Some object files may have an identifier string embedded in them, - /// e.g. in a Mach-O core file using the LC_IDENT load command (which - /// is obsolete, but can still be found in some old files) + /// Some object files may have an identifier string embedded in them, e.g. + /// in a Mach-O core file using the LC_IDENT load command (which is + /// obsolete, but can still be found in some old files) /// /// @return /// Returns the identifier string if one exists, else an empty @@ -589,11 +581,11 @@ public: } //------------------------------------------------------------------ - /// When the ObjectFile is a core file, lldb needs to locate the - /// "binary" in the core file. lldb can iterate over the pages looking - /// for a valid binary, but some core files may have metadata - /// describing where the main binary is exactly which removes ambiguity - /// when there are multiple binaries present in the captured memory pages. + /// When the ObjectFile is a core file, lldb needs to locate the "binary" in + /// the core file. lldb can iterate over the pages looking for a valid + /// binary, but some core files may have metadata describing where the main + /// binary is exactly which removes ambiguity when there are multiple + /// binaries present in the captured memory pages. /// /// @param[out] address /// If the address of the binary is specified, this will be set. @@ -620,13 +612,12 @@ public: } //------------------------------------------------------------------ - /// The object file should be able to calculate its type by looking - /// at its file header and possibly the sections or other data in - /// the object file. The file type is used in the debugger to help - /// select the correct plug-ins for the job at hand, so this is - /// important to get right. If any eTypeXXX definitions do not match - /// up with the type of file you are loading, please feel free to - /// add a new enumeration value. + /// The object file should be able to calculate its type by looking at its + /// file header and possibly the sections or other data in the object file. + /// The file type is used in the debugger to help select the correct plug- + /// ins for the job at hand, so this is important to get right. If any + /// eTypeXXX definitions do not match up with the type of file you are + /// loading, please feel free to add a new enumeration value. /// /// @return /// The calculated file type for the current object file. @@ -634,20 +625,19 @@ public: virtual Type CalculateType() = 0; //------------------------------------------------------------------ - /// In cases where the type can't be calculated (elf files), this - /// routine allows someone to explicitly set it. As an example, - /// SymbolVendorELF uses this routine to set eTypeDebugInfo when - /// loading debug link files. + /// In cases where the type can't be calculated (elf files), this routine + /// allows someone to explicitly set it. As an example, SymbolVendorELF uses + /// this routine to set eTypeDebugInfo when loading debug link files. virtual void SetType(Type type) { m_type = type; } //------------------------------------------------------------------ - /// The object file should be able to calculate the strata of the - /// object file. + /// The object file should be able to calculate the strata of the object + /// file. /// - /// Many object files for platforms might be for either user space - /// debugging or for kernel debugging. If your object file subclass - /// can figure this out, it will help with debugger plug-in selection - /// when it comes time to debug. + /// Many object files for platforms might be for either user space debugging + /// or for kernel debugging. If your object file subclass can figure this + /// out, it will help with debugger plug-in selection when it comes time to + /// debug. /// /// @return /// The calculated object file strata for the current object @@ -658,16 +648,16 @@ public: //------------------------------------------------------------------ /// Get the object file version numbers. /// - /// Many object files have a set of version numbers that describe - /// the version of the executable or shared library. Typically there - /// are major, minor and build, but there may be more. This function - /// will extract the versions from object files if they are available. + /// Many object files have a set of version numbers that describe the + /// version of the executable or shared library. Typically there are major, + /// minor and build, but there may be more. This function will extract the + /// versions from object files if they are available. /// - /// If \a versions is NULL, or if \a num_versions is 0, the return - /// value will indicate how many version numbers are available in - /// this object file. Then a subsequent call can be made to this - /// function with a value of \a versions and \a num_versions that - /// has enough storage to store some or all version numbers. + /// If \a versions is NULL, or if \a num_versions is 0, the return value + /// will indicate how many version numbers are available in this object + /// file. Then a subsequent call can be made to this function with a value + /// of \a versions and \a num_versions that has enough storage to store some + /// or all version numbers. /// /// @param[out] versions /// A pointer to an array of uint32_t types that is \a num_versions @@ -706,14 +696,14 @@ public: //------------------------------------------------------------------ /// Get the minimum OS version this object file can run on. /// - /// Some object files have information that specifies the minimum OS - /// version that they can be used on. + /// Some object files have information that specifies the minimum OS version + /// that they can be used on. /// - /// If \a versions is NULL, or if \a num_versions is 0, the return - /// value will indicate how many version numbers are available in - /// this object file. Then a subsequent call can be made to this - /// function with a value of \a versions and \a num_versions that - /// has enough storage to store some or all version numbers. + /// If \a versions is NULL, or if \a num_versions is 0, the return value + /// will indicate how many version numbers are available in this object + /// file. Then a subsequent call can be made to this function with a value + /// of \a versions and \a num_versions that has enough storage to store some + /// or all version numbers. /// /// @param[out] versions /// A pointer to an array of uint32_t types that is \a num_versions @@ -767,12 +757,11 @@ public: //------------------------------------------------------------------ /// Return true if this file is a dynamic link editor (dyld) /// - /// Often times dyld has symbols that mirror symbols in libc and - /// other shared libraries (like "malloc" and "free") and the user - /// does _not_ want to stop in these shared libraries by default. - /// We can ask the ObjectFile if it is such a file and should be - /// avoided for things like settings breakpoints and doing function - /// lookups for expressions. + /// Often times dyld has symbols that mirror symbols in libc and other + /// shared libraries (like "malloc" and "free") and the user does _not_ want + /// to stop in these shared libraries by default. We can ask the ObjectFile + /// if it is such a file and should be avoided for things like settings + /// breakpoints and doing function lookups for expressions. //------------------------------------------------------------------ virtual bool GetIsDynamicLinkEditor() { return false; } @@ -833,9 +822,9 @@ public: //------------------------------------------------------------------ /// Loads this objfile to memory. /// - /// Loads the bits needed to create an executable image to the memory. - /// It is useful with bare-metal targets where target does not have the - /// ability to start a process itself. + /// Loads the bits needed to create an executable image to the memory. It is + /// useful with bare-metal targets where target does not have the ability to + /// start a process itself. /// /// @param[in] target /// Target where to load. @@ -868,9 +857,9 @@ protected: uint32_t m_synthetic_symbol_idx; //------------------------------------------------------------------ - /// Sets the architecture for a module. At present the architecture - /// can only be set if it is invalid. It is not allowed to switch from - /// one concrete architecture to another. + /// Sets the architecture for a module. At present the architecture can + /// only be set if it is invalid. It is not allowed to switch from one + /// concrete architecture to another. /// /// @param[in] new_arch /// The architecture this module will be set to. diff --git a/lldb/include/lldb/Symbol/SymbolContext.h b/lldb/include/lldb/Symbol/SymbolContext.h index f84b7cf916f..0ec0006f193 100644 --- a/lldb/include/lldb/Symbol/SymbolContext.h +++ b/lldb/include/lldb/Symbol/SymbolContext.h @@ -29,14 +29,12 @@ namespace lldb_private { class SymbolContextScope; //---------------------------------------------------------------------- -/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" -/// @brief Defines a symbol context baton that can be handed other debug -/// core functions. +/// @class SymbolContext SymbolContext.h "lldb/Symbol/SymbolContext.h" Defines +/// a symbol context baton that can be handed other debug core functions. /// -/// Many debugger functions require a context when doing lookups. This -/// class provides a common structure that can be used as the result -/// of a query that can contain a single result. Examples of such -/// queries include +/// Many debugger functions require a context when doing lookups. This class +/// provides a common structure that can be used as the result of a query that +/// can contain a single result. Examples of such queries include /// @li Looking up a load address. //---------------------------------------------------------------------- class SymbolContext { @@ -44,14 +42,14 @@ public: //------------------------------------------------------------------ /// Default constructor. /// - /// Initialize all pointer members to nullptr and all struct members - /// to their default state. + /// Initialize all pointer members to nullptr and all struct members to + /// their default state. //------------------------------------------------------------------ SymbolContext(); //------------------------------------------------------------------ - /// Construct with an object that knows how to reconstruct its - /// symbol context. + /// Construct with an object that knows how to reconstruct its symbol + /// context. /// /// @param[in] sc_scope /// A symbol context scope object that knows how to reconstruct @@ -60,8 +58,8 @@ public: explicit SymbolContext(SymbolContextScope *sc_scope); //------------------------------------------------------------------ - /// Construct with module, and optional compile unit, function, - /// block, line table, line entry and symbol. + /// Construct with module, and optional compile unit, function, block, line + /// table, line entry and symbol. /// /// Initialize all pointer to the specified values. /// @@ -112,8 +110,8 @@ public: //------------------------------------------------------------------ /// Assignment operator. /// - /// Copies the address value from another SymbolContext object \a - /// rhs into \a this object. + /// Copies the address value from another SymbolContext object \a rhs into + /// \a this object. /// /// @param[in] rhs /// A const SymbolContext object reference to copy. @@ -126,16 +124,16 @@ public: //------------------------------------------------------------------ /// Clear the object's state. /// - /// Resets all pointer members to nullptr, and clears any class objects - /// to their default state. + /// Resets all pointer members to nullptr, and clears any class objects to + /// their default state. //------------------------------------------------------------------ void Clear(bool clear_target); //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of this object to the - /// supplied stream \a s. + /// Dump a description of the contents of this object to the supplied stream + /// \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -145,13 +143,12 @@ public: //------------------------------------------------------------------ /// Dump the stop context in this object to a Stream. /// - /// Dump the best description of this object to the stream. The - /// information displayed depends on the amount and quality of the - /// information in this context. If a module, function, file and - /// line number are available, they will be dumped. If only a - /// module and function or symbol name with offset is available, - /// that will be output. Else just the address at which the target - /// was stopped will be displayed. + /// Dump the best description of this object to the stream. The information + /// displayed depends on the amount and quality of the information in this + /// context. If a module, function, file and line number are available, they + /// will be dumped. If only a module and function or symbol name with offset + /// is available, that will be output. Else just the address at which the + /// target was stopped will be displayed. /// /// @param[in] s /// The stream to which to dump the object description. @@ -267,21 +264,21 @@ public: lldb::LanguageType GetLanguage() const; //------------------------------------------------------------------ - /// Find a block that defines the function represented by this - /// symbol context. + /// Find a block that defines the function represented by this symbol + /// context. /// - /// If this symbol context points to a block that is an inlined - /// function, or is contained within an inlined function, the block - /// that defines the inlined function is returned. + /// If this symbol context points to a block that is an inlined function, or + /// is contained within an inlined function, the block that defines the + /// inlined function is returned. /// - /// If this symbol context has no block in it, or the block is not - /// itself an inlined function block or contained within one, we - /// return the top level function block. + /// If this symbol context has no block in it, or the block is not itself an + /// inlined function block or contained within one, we return the top level + /// function block. /// - /// This is a handy function to call when you want to get the block - /// whose variable list will include the arguments for the function - /// that is represented by this symbol context (whether the function - /// is an inline function or not). + /// This is a handy function to call when you want to get the block whose + /// variable list will include the arguments for the function that is + /// represented by this symbol context (whether the function is an inline + /// function or not). /// /// @return /// The block object pointer that defines the function that is @@ -290,8 +287,8 @@ public: Block *GetFunctionBlock(); //------------------------------------------------------------------ - /// If this symbol context represents a function that is a method, - /// return true and provide information about the method. + /// If this symbol context represents a function that is a method, return + /// true and provide information about the method. /// /// @param[out] language /// If \b true is returned, the language for the method. @@ -313,8 +310,7 @@ public: ConstString &language_object_name); //------------------------------------------------------------------ - /// Sorts the types in TypeMap according to SymbolContext - /// to TypeList + /// Sorts the types in TypeMap according to SymbolContext to TypeList /// //------------------------------------------------------------------ void SortTypeList(TypeMap &type_map, TypeList &type_list) const; @@ -322,8 +318,8 @@ public: //------------------------------------------------------------------ /// Find a name of the innermost function for the symbol context. /// - /// For instance, if the symbol context contains an inlined block, - /// it will return the inlined function name. + /// For instance, if the symbol context contains an inlined block, it will + /// return the inlined function name. /// /// @param[in] prefer_mangled /// if \btrue, then the mangled name will be returned if there @@ -339,14 +335,13 @@ public: //------------------------------------------------------------------ /// Get the line entry that corresponds to the function. /// - /// If the symbol context contains an inlined block, the line entry - /// for the start address of the inlined function will be returned, - /// otherwise the line entry for the start address of the function - /// will be returned. This can be used after doing a - /// Module::FindFunctions(...) or ModuleList::FindFunctions(...) - /// call in order to get the correct line table information for - /// the symbol context. - /// it will return the inlined function name. + /// If the symbol context contains an inlined block, the line entry for the + /// start address of the inlined function will be returned, otherwise the + /// line entry for the start address of the function will be returned. This + /// can be used after doing a Module::FindFunctions(...) or + /// ModuleList::FindFunctions(...) call in order to get the correct line + /// table information for the symbol context. it will return the inlined + /// function name. /// /// @param[in] prefer_mangled /// if \btrue, then the mangled name will be returned if there @@ -361,8 +356,8 @@ public: //------------------------------------------------------------------ /// Find the block containing the inlined block that contains this block. /// - /// For instance, if the symbol context contains an inlined block, - /// it will return the inlined function name. + /// For instance, if the symbol context contains an inlined block, it will + /// return the inlined function name. /// /// @param[in] curr_frame_pc /// The address within the block of this object. @@ -440,11 +435,11 @@ private: //---------------------------------------------------------------------- /// @class SymbolContextList SymbolContext.h "lldb/Symbol/SymbolContext.h" -/// @brief Defines a list of symbol context objects. +/// Defines a list of symbol context objects. /// -/// This class provides a common structure that can be used to contain -/// the result of a query that can contain a multiple results. Examples -/// of such queries include: +/// This class provides a common structure that can be used to contain the +/// result of a query that can contain a multiple results. Examples of such +/// queries include: /// @li Looking up a function by name. /// @li Finding all addresses for a specified file and line number. //---------------------------------------------------------------------- @@ -491,8 +486,8 @@ public: //------------------------------------------------------------------ /// Dump a description of this object to a Stream. /// - /// Dump a description of the contents of each symbol context in - /// the list to the supplied stream \a s. + /// Dump a description of the contents of each symbol context in the list to + /// the supplied stream \a s. /// /// @param[in] s /// The stream to which to dump the object description. @@ -502,8 +497,8 @@ public: //------------------------------------------------------------------ /// Get accessor for a symbol context at index \a idx. /// - /// Dump a description of the contents of each symbol context in - /// the list to the supplied stream \a s. + /// Dump a description of the contents of each symbol context in the list to + /// the supplied stream \a s. /// /// @param[in] idx /// The zero based index into the symbol context list. @@ -521,8 +516,8 @@ public: //------------------------------------------------------------------ /// Direct reference accessor for a symbol context at index \a idx. /// - /// The index \a idx must be a valid index, no error checking will - /// be done to ensure that it is valid. + /// The index \a idx must be a valid index, no error checking will be done + /// to ensure that it is valid. /// /// @param[in] idx /// The zero based index into the symbol context list. diff --git a/lldb/include/lldb/Symbol/SymbolContextScope.h b/lldb/include/lldb/Symbol/SymbolContextScope.h index 926e34bc03a..c2fbb5272fc 100644 --- a/lldb/include/lldb/Symbol/SymbolContextScope.h +++ b/lldb/include/lldb/Symbol/SymbolContextScope.h @@ -20,16 +20,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class SymbolContextScope SymbolContextScope.h -/// "lldb/Symbol/SymbolContextScope.h" -/// @brief Inherit from this if your object is part of a symbol context +/// "lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is +/// part of a symbol context /// and can reconstruct its symbol context. /// -/// Many objects that are part of a symbol context that have pointers -/// back to parent objects that own them. Any members of a symbol -/// context that, once they are built, will not go away, can inherit -/// from this pure virtual class and can then reconstruct their symbol -/// context without having to keep a complete SymbolContext object in -/// the object. +/// Many objects that are part of a symbol context that have pointers back to +/// parent objects that own them. Any members of a symbol context that, once +/// they are built, will not go away, can inherit from this pure virtual class +/// and can then reconstruct their symbol context without having to keep a +/// complete SymbolContext object in the object. /// /// Examples of these objects include: /// @li Module @@ -38,14 +37,14 @@ namespace lldb_private { /// @li Block /// @li Symbol /// -/// Other objects can store a "SymbolContextScope *" using any pointers -/// to one of the above objects. This allows clients to hold onto a -/// pointer that uniquely will identify a symbol context. Those clients -/// can then always reconstruct the symbol context using the pointer, or -/// use it to uniquely identify a symbol context for an object. +/// Other objects can store a "SymbolContextScope *" using any pointers to one +/// of the above objects. This allows clients to hold onto a pointer that +/// uniquely will identify a symbol context. Those clients can then always +/// reconstruct the symbol context using the pointer, or use it to uniquely +/// identify a symbol context for an object. /// -/// Example objects include that currently use "SymbolContextScope *" -/// objects include: +/// Example objects include that currently use "SymbolContextScope *" objects +/// include: /// @li Variable objects that can reconstruct where they are scoped /// by making sure the SymbolContextScope * comes from the scope /// in which the variable was declared. If a variable is a global, @@ -63,11 +62,11 @@ namespace lldb_private { /// location) match within the same thread, that the stack /// frame is the same as the previous stack frame. /// -/// Objects that adhere to this protocol can reconstruct enough of a -/// symbol context to allow functions that take a symbol context to be -/// called. Lists can also be created using a SymbolContextScope* and -/// and object pairs that allow large collections of objects to be -/// passed around with minimal overhead. +/// Objects that adhere to this protocol can reconstruct enough of a symbol +/// context to allow functions that take a symbol context to be called. Lists +/// can also be created using a SymbolContextScope* and and object pairs that +/// allow large collections of objects to be passed around with minimal +/// overhead. //---------------------------------------------------------------------- class SymbolContextScope { public: @@ -76,9 +75,9 @@ public: //------------------------------------------------------------------ /// Reconstruct the object's symbol context into \a sc. /// - /// The object should fill in as much of the SymbolContext as it - /// can so function calls that require a symbol context can be made - /// for the given object. + /// The object should fill in as much of the SymbolContext as it can so + /// function calls that require a symbol context can be made for the given + /// object. /// /// @param[out] sc /// A symbol context object pointer that gets filled in. @@ -100,9 +99,9 @@ public: //------------------------------------------------------------------ /// Dump the object's symbol context to the stream \a s. /// - /// The object should dump its symbol context to the stream \a s. - /// This function is widely used in the DumpDebug and verbose output - /// for lldb objects. + /// The object should dump its symbol context to the stream \a s. This + /// function is widely used in the DumpDebug and verbose output for lldb + /// objects. /// /// @param[in] s /// The stream to which to dump the object's symbol context. diff --git a/lldb/include/lldb/Target/DynamicLoader.h b/lldb/include/lldb/Target/DynamicLoader.h index 35da9bb6af6..de9c4e233b0 100644 --- a/lldb/include/lldb/Target/DynamicLoader.h +++ b/lldb/include/lldb/Target/DynamicLoader.h @@ -48,24 +48,21 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class DynamicLoader DynamicLoader.h "lldb/Target/DynamicLoader.h" -/// @brief A plug-in interface definition class for dynamic loaders. +/// A plug-in interface definition class for dynamic loaders. /// /// Dynamic loader plug-ins track image (shared library) loading and -/// unloading. The class is initialized given a live process that is -/// halted at its entry point or just after attaching. +/// unloading. The class is initialized given a live process that is halted at +/// its entry point or just after attaching. /// -/// Dynamic loader plug-ins can track the process by registering -/// callbacks using the: -/// Process::RegisterNotificationCallbacks (const Notifications&) +/// Dynamic loader plug-ins can track the process by registering callbacks +/// using the: Process::RegisterNotificationCallbacks (const Notifications&) /// function. /// -/// Breakpoints can also be set in the process which can register -/// functions that get called using: -/// Process::BreakpointSetCallback (lldb::user_id_t, BreakpointHitCallback, void -/// *). -/// These breakpoint callbacks return a boolean value that indicates if -/// the process should continue or halt and should return the global -/// setting for this using: +/// Breakpoints can also be set in the process which can register functions +/// that get called using: Process::BreakpointSetCallback (lldb::user_id_t, +/// BreakpointHitCallback, void *). These breakpoint callbacks return a +/// boolean value that indicates if the process should continue or halt and +/// should return the global setting for this using: /// DynamicLoader::StopWhenImagesChange() const. //---------------------------------------------------------------------- class DynamicLoader : public PluginInterface { @@ -73,9 +70,8 @@ public: //------------------------------------------------------------------ /// Find a dynamic loader plugin for a given process. /// - /// Scans the installed DynamicLoader plug-ins and tries to find - /// an instance that can be used to track image changes in \a - /// process. + /// Scans the installed DynamicLoader plug-ins and tries to find an instance + /// that can be used to track image changes in \a process. /// /// @param[in] process /// The process for which to try and locate a dynamic loader @@ -95,45 +91,44 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited from by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// from by the plug-in instance. //------------------------------------------------------------------ virtual ~DynamicLoader() override; //------------------------------------------------------------------ /// Called after attaching a process. /// - /// Allow DynamicLoader plug-ins to execute some code after - /// attaching to a process. + /// Allow DynamicLoader plug-ins to execute some code after attaching to a + /// process. //------------------------------------------------------------------ virtual void DidAttach() = 0; //------------------------------------------------------------------ /// Called after launching a process. /// - /// Allow DynamicLoader plug-ins to execute some code after - /// the process has stopped for the first time on launch. + /// Allow DynamicLoader plug-ins to execute some code after the process has + /// stopped for the first time on launch. //------------------------------------------------------------------ virtual void DidLaunch() = 0; //------------------------------------------------------------------ - /// Helper function that can be used to detect when a process has - /// called exec and is now a new and different process. This can - /// be called when necessary to try and detect the exec. The process - /// might be able to answer this question, but sometimes it might - /// not be able and the dynamic loader often knows what the program - /// entry point is. So the process and the dynamic loader can work - /// together to detect this. + /// Helper function that can be used to detect when a process has called + /// exec and is now a new and different process. This can be called when + /// necessary to try and detect the exec. The process might be able to + /// answer this question, but sometimes it might not be able and the dynamic + /// loader often knows what the program entry point is. So the process and + /// the dynamic loader can work together to detect this. //------------------------------------------------------------------ virtual bool ProcessDidExec() { return false; } //------------------------------------------------------------------ /// Get whether the process should stop when images change. /// - /// When images (executables and shared libraries) get loaded or - /// unloaded, often debug sessions will want to try and resolve or - /// unresolve breakpoints that are set in these images. Any - /// breakpoints set by DynamicLoader plug-in instances should - /// return this value to ensure consistent debug session behaviour. + /// When images (executables and shared libraries) get loaded or unloaded, + /// often debug sessions will want to try and resolve or unresolve + /// breakpoints that are set in these images. Any breakpoints set by + /// DynamicLoader plug-in instances should return this value to ensure + /// consistent debug session behaviour. /// /// @return /// Returns \b true if the process should stop when images @@ -144,11 +139,11 @@ public: //------------------------------------------------------------------ /// Set whether the process should stop when images change. /// - /// When images (executables and shared libraries) get loaded or - /// unloaded, often debug sessions will want to try and resolve or - /// unresolve breakpoints that are set in these images. The default - /// is set so that the process stops when images change, but this - /// can be overridden using this function callback. + /// When images (executables and shared libraries) get loaded or unloaded, + /// often debug sessions will want to try and resolve or unresolve + /// breakpoints that are set in these images. The default is set so that the + /// process stops when images change, but this can be overridden using this + /// function callback. /// /// @param[in] stop /// Boolean value that indicates whether the process should stop @@ -157,8 +152,8 @@ public: void SetStopWhenImagesChange(bool stop); //------------------------------------------------------------------ - /// Provides a plan to step through the dynamic loader trampoline - /// for the current state of \a thread. + /// Provides a plan to step through the dynamic loader trampoline for the + /// current state of \a thread. /// /// /// @param[in] stop_others @@ -173,12 +168,9 @@ public: //------------------------------------------------------------------ /// Some dynamic loaders provide features where there are a group of symbols - /// "equivalent to" - /// a given symbol one of which will be chosen when the symbol is bound. If - /// you want to - /// set a breakpoint on one of these symbols, you really need to set it on all - /// the - /// equivalent symbols. + /// "equivalent to" a given symbol one of which will be chosen when the + /// symbol is bound. If you want to set a breakpoint on one of these + /// symbols, you really need to set it on all the equivalent symbols. /// /// /// @param[in] original_symbol @@ -201,13 +193,12 @@ public: } //------------------------------------------------------------------ - /// Ask if it is ok to try and load or unload an shared library - /// (image). + /// Ask if it is ok to try and load or unload an shared library (image). /// - /// The dynamic loader often knows when it would be ok to try and - /// load or unload a shared library. This function call allows the - /// dynamic loader plug-ins to check any current dyld state to make - /// sure it is an ok time to load a shared library. + /// The dynamic loader often knows when it would be ok to try and load or + /// unload a shared library. This function call allows the dynamic loader + /// plug-ins to check any current dyld state to make sure it is an ok time + /// to load a shared library. /// /// @return /// \b true if it is currently ok to try and load a shared @@ -216,20 +207,20 @@ public: virtual Status CanLoadImage() = 0; //------------------------------------------------------------------ - /// Ask if the eh_frame information for the given SymbolContext should - /// be relied on even when it's the first frame in a stack unwind. + /// Ask if the eh_frame information for the given SymbolContext should be + /// relied on even when it's the first frame in a stack unwind. /// - /// The CFI instructions from the eh_frame section are normally only - /// valid at call sites -- places where a program could throw an - /// exception and need to unwind out. But some Modules may be known - /// to the system as having reliable eh_frame information at all call - /// sites. This would be the case if the Module's contents are largely - /// hand-written assembly with hand-written eh_frame information. - /// Normally when unwinding from a function at the beginning of a stack - /// unwind lldb will examine the assembly instructions to understand - /// how the stack frame is set up and where saved registers are stored. - /// But with hand-written assembly this is not reliable enough -- we need - /// to consult those function's hand-written eh_frame information. + /// The CFI instructions from the eh_frame section are normally only valid + /// at call sites -- places where a program could throw an exception and + /// need to unwind out. But some Modules may be known to the system as + /// having reliable eh_frame information at all call sites. This would be + /// the case if the Module's contents are largely hand-written assembly with + /// hand-written eh_frame information. Normally when unwinding from a + /// function at the beginning of a stack unwind lldb will examine the + /// assembly instructions to understand how the stack frame is set up and + /// where saved registers are stored. But with hand-written assembly this is + /// not reliable enough -- we need to consult those function's hand-written + /// eh_frame information. /// /// @return /// \b True if the symbol context should use eh_frame instructions @@ -271,17 +262,17 @@ public: //------------------------------------------------------------------ /// Get information about the shared cache for a process, if possible. /// - /// On some systems (e.g. Darwin based systems), a set of libraries - /// that are common to most processes may be put in a single region - /// of memory and mapped into every process, this is called the - /// shared cache, as a performance optimization. + /// On some systems (e.g. Darwin based systems), a set of libraries that are + /// common to most processes may be put in a single region of memory and + /// mapped into every process, this is called the shared cache, as a + /// performance optimization. /// /// Many targets will not have the concept of a shared cache. /// - /// Depending on how the DynamicLoader gathers information about the - /// shared cache, it may be able to only return basic information - - /// like the UUID of the cache - or it may be able to return additional - /// information about the cache. + /// Depending on how the DynamicLoader gathers information about the shared + /// cache, it may be able to only return basic information - like the UUID + /// of the cache - or it may be able to return additional information about + /// the cache. /// /// @param[out] base_address /// The base address (load address) of the shared cache. diff --git a/lldb/include/lldb/Target/ExecutionContext.h b/lldb/include/lldb/Target/ExecutionContext.h index cfd52534955..21a2bba8727 100644 --- a/lldb/include/lldb/Target/ExecutionContext.h +++ b/lldb/include/lldb/Target/ExecutionContext.h @@ -22,61 +22,59 @@ namespace lldb_private { //===----------------------------------------------------------------------===// -/// Execution context objects refer to objects in the execution of the -/// program that is being debugged. The consist of one or more of the -/// following objects: target, process, thread, and frame. Many objects -/// in the debugger need to track different executions contexts. For -/// example, a local function variable might have an execution context -/// that refers to a stack frame. A global or static variable might -/// refer to a target since a stack frame isn't required in order to -/// evaluate a global or static variable (a process isn't necessarily -/// needed for a global variable since we might be able to read the -/// variable value from a data section in one of the object files in +/// Execution context objects refer to objects in the execution of the program +/// that is being debugged. The consist of one or more of the following +/// objects: target, process, thread, and frame. Many objects in the debugger +/// need to track different executions contexts. For example, a local function +/// variable might have an execution context that refers to a stack frame. A +/// global or static variable might refer to a target since a stack frame +/// isn't required in order to evaluate a global or static variable (a process +/// isn't necessarily needed for a global variable since we might be able to +/// read the variable value from a data section in one of the object files in /// a target). There are two types of objects that hold onto execution -/// contexts: ExecutionContextRef and ExecutionContext. Both of these -/// objects are described below. +/// contexts: ExecutionContextRef and ExecutionContext. Both of these objects +/// are described below. /// /// Not all objects in an ExectionContext objects will be valid. If you want -/// to refer strongly (ExectionContext) or weakly (ExectionContextRef) to -/// a process, then only the process and target references will be valid. -/// For threads, only the thread, process and target references will be -/// filled in. For frames, all of the objects will be filled in. +/// to refer strongly (ExectionContext) or weakly (ExectionContextRef) to a +/// process, then only the process and target references will be valid. For +/// threads, only the thread, process and target references will be filled in. +/// For frames, all of the objects will be filled in. /// -/// These classes are designed to be used as baton objects that get passed -/// to a wide variety of functions that require execution contexts. +/// These classes are designed to be used as baton objects that get passed to +/// a wide variety of functions that require execution contexts. //===----------------------------------------------------------------------===// //---------------------------------------------------------------------- /// @class ExecutionContextRef ExecutionContext.h /// "lldb/Target/ExecutionContext.h" -/// @brief A class that holds a weak reference to an execution context. +/// A class that holds a weak reference to an execution context. /// -/// ExecutionContextRef objects are designed to hold onto an execution -/// context that might change over time. For example, if an object wants -/// to refer to a stack frame, it should hold onto an ExecutionContextRef -/// to a frame object. The backing object that represents the stack frame -/// might change over time and instances of this object can track the logical -/// object that refers to a frame even if it does change. +/// ExecutionContextRef objects are designed to hold onto an execution context +/// that might change over time. For example, if an object wants to refer to a +/// stack frame, it should hold onto an ExecutionContextRef to a frame object. +/// The backing object that represents the stack frame might change over time +/// and instances of this object can track the logical object that refers to a +/// frame even if it does change. /// /// These objects also don't keep execution objects around longer than they -/// should since they use weak pointers. For example if an object refers -/// to a stack frame and a stack frame is no longer in a thread, then a -/// ExecutionContextRef object that refers to that frame will not be able -/// to get a shared pointer to those objects since they are no longer around. +/// should since they use weak pointers. For example if an object refers to a +/// stack frame and a stack frame is no longer in a thread, then a +/// ExecutionContextRef object that refers to that frame will not be able to +/// get a shared pointer to those objects since they are no longer around. /// -/// ExecutionContextRef objects can also be used as objects in classes -/// that want to track a "previous execution context". Since the weak -/// references to the execution objects (target, process, thread and frame) -/// don't keep these objects around, they are safe to keep around. +/// ExecutionContextRef objects can also be used as objects in classes that +/// want to track a "previous execution context". Since the weak references to +/// the execution objects (target, process, thread and frame) don't keep these +/// objects around, they are safe to keep around. /// -/// The general rule of thumb is all long lived objects that want to -/// refer to execution contexts should use ExecutionContextRef objects. -/// The ExecutionContext class is used to temporarily get shared -/// pointers to any execution context objects that are still around -/// so they are guaranteed to exist during a function that requires the -/// objects. ExecutionContext objects should NOT be used for long term -/// storage since they will keep objects alive with extra shared pointer -/// references to these objects. +/// The general rule of thumb is all long lived objects that want to refer to +/// execution contexts should use ExecutionContextRef objects. The +/// ExecutionContext class is used to temporarily get shared pointers to any +/// execution context objects that are still around so they are guaranteed to +/// exist during a function that requires the objects. ExecutionContext +/// objects should NOT be used for long term storage since they will keep +/// objects alive with extra shared pointer references to these objects. //---------------------------------------------------------------------- class ExecutionContextRef { public: @@ -93,9 +91,9 @@ public: //------------------------------------------------------------------ /// Construct using an ExecutionContext object that might be nullptr. /// - /// If \a exe_ctx_ptr is valid, then make weak references to any - /// valid objects in the ExecutionContext, otherwise no weak - /// references to any execution context objects will be made. + /// If \a exe_ctx_ptr is valid, then make weak references to any valid + /// objects in the ExecutionContext, otherwise no weak references to any + /// execution context objects will be made. //------------------------------------------------------------------ ExecutionContextRef(const ExecutionContext *exe_ctx_ptr); @@ -107,38 +105,37 @@ public: ExecutionContextRef(const ExecutionContext &exe_ctx); //------------------------------------------------------------------ - /// Construct using the target and all the selected items inside of it - /// (the process and its selected thread, and the thread's selected - /// frame). If there is no selected thread, default to the first thread - /// If there is no selected frame, default to the first frame. + /// Construct using the target and all the selected items inside of it (the + /// process and its selected thread, and the thread's selected frame). If + /// there is no selected thread, default to the first thread If there is no + /// selected frame, default to the first frame. //------------------------------------------------------------------ ExecutionContextRef(Target *target, bool adopt_selected); //------------------------------------------------------------------ /// Construct using an execution context scope. /// - /// If the ExecutionContextScope object is valid and refers to a frame, - /// make weak references too the frame, thread, process and target. - /// If the ExecutionContextScope object is valid and refers to a thread, - /// make weak references too the thread, process and target. - /// If the ExecutionContextScope object is valid and refers to a process, - /// make weak references too the process and target. - /// If the ExecutionContextScope object is valid and refers to a target, - /// make weak references too the target. + /// If the ExecutionContextScope object is valid and refers to a frame, make + /// weak references too the frame, thread, process and target. If the + /// ExecutionContextScope object is valid and refers to a thread, make weak + /// references too the thread, process and target. If the + /// ExecutionContextScope object is valid and refers to a process, make weak + /// references too the process and target. If the ExecutionContextScope + /// object is valid and refers to a target, make weak references too the + /// target. //------------------------------------------------------------------ ExecutionContextRef(ExecutionContextScope *exe_scope); //------------------------------------------------------------------ /// Construct using an execution context scope. /// - /// If the ExecutionContextScope object refers to a frame, - /// make weak references too the frame, thread, process and target. - /// If the ExecutionContextScope object refers to a thread, - /// make weak references too the thread, process and target. - /// If the ExecutionContextScope object refers to a process, - /// make weak references too the process and target. - /// If the ExecutionContextScope object refers to a target, - /// make weak references too the target. + /// If the ExecutionContextScope object refers to a frame, make weak + /// references too the frame, thread, process and target. If the + /// ExecutionContextScope object refers to a thread, make weak references + /// too the thread, process and target. If the ExecutionContextScope object + /// refers to a process, make weak references too the process and target. If + /// the ExecutionContextScope object refers to a target, make weak + /// references too the target. //------------------------------------------------------------------ ExecutionContextRef(ExecutionContextScope &exe_scope); @@ -167,33 +164,33 @@ public: void Clear(); //------------------------------------------------------------------ - /// Set accessor that creates a weak reference to the target - /// referenced in \a target_sp. + /// Set accessor that creates a weak reference to the target referenced in + /// \a target_sp. /// - /// If \a target_sp is valid this object will create a weak - /// reference to that object, otherwise any previous target weak - /// reference contained in this object will be reset. + /// If \a target_sp is valid this object will create a weak reference to + /// that object, otherwise any previous target weak reference contained in + /// this object will be reset. /// - /// Only the weak reference to the target will be updated, no other - /// weak references will be modified. If you want this execution - /// context to make a weak reference to the target's process, use - /// the ExecutionContextRef::SetContext() functions. + /// Only the weak reference to the target will be updated, no other weak + /// references will be modified. If you want this execution context to make + /// a weak reference to the target's process, use the + /// ExecutionContextRef::SetContext() functions. /// /// @see ExecutionContextRef::SetContext(const lldb::TargetSP &, bool) //------------------------------------------------------------------ void SetTargetSP(const lldb::TargetSP &target_sp); //------------------------------------------------------------------ - /// Set accessor that creates a weak reference to the process - /// referenced in \a process_sp. + /// Set accessor that creates a weak reference to the process referenced in + /// \a process_sp. /// - /// If \a process_sp is valid this object will create a weak - /// reference to that object, otherwise any previous process weak - /// reference contained in this object will be reset. + /// If \a process_sp is valid this object will create a weak reference to + /// that object, otherwise any previous process weak reference contained in + /// this object will be reset. /// - /// Only the weak reference to the process will be updated, no other - /// weak references will be modified. If you want this execution - /// context to make a weak reference to the target, use the + /// Only the weak reference to the process will be updated, no other weak + /// references will be modified. If you want this execution context to make + /// a weak reference to the target, use the /// ExecutionContextRef::SetContext() functions. /// /// @see ExecutionContextRef::SetContext(const lldb::ProcessSP &) @@ -201,34 +198,34 @@ public: void SetProcessSP(const lldb::ProcessSP &process_sp); //------------------------------------------------------------------ - /// Set accessor that creates a weak reference to the thread - /// referenced in \a thread_sp. + /// Set accessor that creates a weak reference to the thread referenced in + /// \a thread_sp. /// - /// If \a thread_sp is valid this object will create a weak - /// reference to that object, otherwise any previous thread weak - /// reference contained in this object will be reset. + /// If \a thread_sp is valid this object will create a weak reference to + /// that object, otherwise any previous thread weak reference contained in + /// this object will be reset. /// - /// Only the weak reference to the thread will be updated, no other - /// weak references will be modified. If you want this execution - /// context to make a weak reference to the thread's process and - /// target, use the ExecutionContextRef::SetContext() functions. + /// Only the weak reference to the thread will be updated, no other weak + /// references will be modified. If you want this execution context to make + /// a weak reference to the thread's process and target, use the + /// ExecutionContextRef::SetContext() functions. /// /// @see ExecutionContextRef::SetContext(const lldb::ThreadSP &) //------------------------------------------------------------------ void SetThreadSP(const lldb::ThreadSP &thread_sp); //------------------------------------------------------------------ - /// Set accessor that creates a weak reference to the frame - /// referenced in \a frame_sp. + /// Set accessor that creates a weak reference to the frame referenced in \a + /// frame_sp. /// - /// If \a frame_sp is valid this object will create a weak - /// reference to that object, otherwise any previous frame weak - /// reference contained in this object will be reset. + /// If \a frame_sp is valid this object will create a weak reference to that + /// object, otherwise any previous frame weak reference contained in this + /// object will be reset. /// - /// Only the weak reference to the frame will be updated, no other - /// weak references will be modified. If you want this execution - /// context to make a weak reference to the frame's thread, process - /// and target, use the ExecutionContextRef::SetContext() functions. + /// Only the weak reference to the frame will be updated, no other weak + /// references will be modified. If you want this execution context to make + /// a weak reference to the frame's thread, process and target, use the + /// ExecutionContextRef::SetContext() functions. /// /// @see ExecutionContextRef::SetContext(const lldb::StackFrameSP &) //------------------------------------------------------------------ @@ -281,28 +278,25 @@ public: //------------------------------------------------------------------ /// Create an ExecutionContext object from this object. /// - /// Create strong references to any execution context objects that - /// are still valid. Any of the returned shared pointers in the - /// ExecutionContext objects is not guaranteed to be valid. - /// @returns + /// Create strong references to any execution context objects that are still + /// valid. Any of the returned shared pointers in the ExecutionContext + /// objects is not guaranteed to be valid. @returns /// An execution context object that has strong references to /// any valid weak references in this object. //------------------------------------------------------------------ ExecutionContext Lock(bool thread_and_frame_only_if_stopped) const; //------------------------------------------------------------------ - /// Returns true if this object has a weak reference to a thread. - /// The return value is only an indication of whether this object has - /// a weak reference and does not indicate whether the weak reference - /// is valid or not. + /// Returns true if this object has a weak reference to a thread. The return + /// value is only an indication of whether this object has a weak reference + /// and does not indicate whether the weak reference is valid or not. //------------------------------------------------------------------ bool HasThreadRef() const { return m_tid != LLDB_INVALID_THREAD_ID; } //------------------------------------------------------------------ - /// Returns true if this object has a weak reference to a frame. - /// The return value is only an indication of whether this object has - /// a weak reference and does not indicate whether the weak reference - /// is valid or not. + /// Returns true if this object has a weak reference to a frame. The return + /// value is only an indication of whether this object has a weak reference + /// and does not indicate whether the weak reference is valid or not. //------------------------------------------------------------------ bool HasFrameRef() const { return m_stack_id.IsValid(); } @@ -327,25 +321,25 @@ protected: }; //---------------------------------------------------------------------- -/// @class ExecutionContext ExecutionContext.h "lldb/Target/ExecutionContext.h" -/// @brief A class that contains an execution context. +/// @class ExecutionContext ExecutionContext.h +/// "lldb/Target/ExecutionContext.h" +/// A class that contains an execution context. /// -/// This baton object can be passed into any function that requires -/// a context that specifies a target, process, thread and frame. -/// These objects are designed to be used for short term execution -/// context object storage while a function might be trying to evaluate -/// something that requires a thread or frame. ExecutionContextRef -/// objects can be used to initialize one of these objects to turn -/// the weak execution context object references to the target, process, -/// thread and frame into strong references (shared pointers) so that -/// functions can guarantee that these objects won't go away in the +/// This baton object can be passed into any function that requires a context +/// that specifies a target, process, thread and frame. These objects are +/// designed to be used for short term execution context object storage while +/// a function might be trying to evaluate something that requires a thread or +/// frame. ExecutionContextRef objects can be used to initialize one of these +/// objects to turn the weak execution context object references to the +/// target, process, thread and frame into strong references (shared pointers) +/// so that functions can guarantee that these objects won't go away in the /// middle of a function. /// -/// ExecutionContext objects should be used as short lived objects -/// (typically on the stack) in order to lock down an execution context -/// for local use and for passing down to other functions that also -/// require specific contexts. They should NOT be used for long term -/// storage, for long term storage use ExecutionContextRef objects. +/// ExecutionContext objects should be used as short lived objects (typically +/// on the stack) in order to lock down an execution context for local use and +/// for passing down to other functions that also require specific contexts. +/// They should NOT be used for long term storage, for long term storage use +/// ExecutionContextRef objects. //---------------------------------------------------------------------- class ExecutionContext { public: @@ -440,14 +434,14 @@ public: /// Returns a pointer to the target object. /// /// The returned pointer might be nullptr. Calling HasTargetScope(), - /// HasProcessScope(), HasThreadScope(), or HasFrameScope() - /// can help to pre-validate this pointer so that this accessor can - /// freely be used without having to check for nullptr each time. + /// HasProcessScope(), HasThreadScope(), or HasFrameScope() can help to pre- + /// validate this pointer so that this accessor can freely be used without + /// having to check for nullptr each time. /// - /// @see ExecutionContext::HasTargetScope() const - /// @see ExecutionContext::HasProcessScope() const - /// @see ExecutionContext::HasThreadScope() const - /// @see ExecutionContext::HasFrameScope() const + /// @see ExecutionContext::HasTargetScope() const @see + /// ExecutionContext::HasProcessScope() const @see + /// ExecutionContext::HasThreadScope() const @see + /// ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ Target *GetTargetPtr() const; @@ -455,13 +449,13 @@ public: /// Returns a pointer to the process object. /// /// The returned pointer might be nullptr. Calling HasProcessScope(), - /// HasThreadScope(), or HasFrameScope() can help to pre-validate - /// this pointer so that this accessor can freely be used without - /// having to check for nullptr each time. + /// HasThreadScope(), or HasFrameScope() can help to pre-validate this + /// pointer so that this accessor can freely be used without having to check + /// for nullptr each time. /// - /// @see ExecutionContext::HasProcessScope() const - /// @see ExecutionContext::HasThreadScope() const - /// @see ExecutionContext::HasFrameScope() const + /// @see ExecutionContext::HasProcessScope() const @see + /// ExecutionContext::HasThreadScope() const @see + /// ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ Process *GetProcessPtr() const; @@ -469,21 +463,21 @@ public: /// Returns a pointer to the thread object. /// /// The returned pointer might be nullptr. Calling HasThreadScope() or - /// HasFrameScope() can help to pre-validate this pointer so that - /// this accessor can freely be used without having to check for - /// nullptr each time. + /// HasFrameScope() can help to pre-validate this pointer so that this + /// accessor can freely be used without having to check for nullptr each + /// time. /// - /// @see ExecutionContext::HasThreadScope() const - /// @see ExecutionContext::HasFrameScope() const + /// @see ExecutionContext::HasThreadScope() const @see + /// ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ Thread *GetThreadPtr() const { return m_thread_sp.get(); } //------------------------------------------------------------------ /// Returns a pointer to the frame object. /// - /// The returned pointer might be nullptr. Calling HasFrameScope(), - /// can help to pre-validate this pointer so that this accessor can - /// freely be used without having to check for nullptr each time. + /// The returned pointer might be nullptr. Calling HasFrameScope(), can help + /// to pre-validate this pointer so that this accessor can freely be used + /// without having to check for nullptr each time. /// /// @see ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ @@ -493,14 +487,13 @@ public: /// Returns a reference to the target object. /// /// Clients should call HasTargetScope(), HasProcessScope(), - /// HasThreadScope(), or HasFrameScope() prior to calling this - /// function to ensure that this ExecutionContext object contains - /// a valid target. + /// HasThreadScope(), or HasFrameScope() prior to calling this function to + /// ensure that this ExecutionContext object contains a valid target. /// - /// @see ExecutionContext::HasTargetScope() const - /// @see ExecutionContext::HasProcessScope() const - /// @see ExecutionContext::HasThreadScope() const - /// @see ExecutionContext::HasFrameScope() const + /// @see ExecutionContext::HasTargetScope() const @see + /// ExecutionContext::HasProcessScope() const @see + /// ExecutionContext::HasThreadScope() const @see + /// ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ Target &GetTargetRef() const; @@ -508,33 +501,32 @@ public: /// Returns a reference to the process object. /// /// Clients should call HasProcessScope(), HasThreadScope(), or - /// HasFrameScope() prior to calling this function to ensure that - /// this ExecutionContext object contains a valid target. + /// HasFrameScope() prior to calling this function to ensure that this + /// ExecutionContext object contains a valid target. /// - /// @see ExecutionContext::HasProcessScope() const - /// @see ExecutionContext::HasThreadScope() const - /// @see ExecutionContext::HasFrameScope() const + /// @see ExecutionContext::HasProcessScope() const @see + /// ExecutionContext::HasThreadScope() const @see + /// ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ Process &GetProcessRef() const; //------------------------------------------------------------------ /// Returns a reference to the thread object. /// - /// Clients should call HasThreadScope(), or HasFrameScope() prior - /// to calling this function to ensure that this ExecutionContext - /// object contains a valid target. + /// Clients should call HasThreadScope(), or HasFrameScope() prior to + /// calling this function to ensure that this ExecutionContext object + /// contains a valid target. /// - /// @see ExecutionContext::HasThreadScope() const - /// @see ExecutionContext::HasFrameScope() const + /// @see ExecutionContext::HasThreadScope() const @see + /// ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ Thread &GetThreadRef() const; //------------------------------------------------------------------ /// Returns a reference to the thread object. /// - /// Clients should call HasFrameScope() prior to calling this - /// function to ensure that this ExecutionContext object contains - /// a valid target. + /// Clients should call HasFrameScope() prior to calling this function to + /// ensure that this ExecutionContext object contains a valid target. /// /// @see ExecutionContext::HasFrameScope() const //------------------------------------------------------------------ @@ -595,8 +587,8 @@ public: void SetTargetPtr(Target *target); //------------------------------------------------------------------ - /// Set accessor to set only the process shared pointer from a - /// process pointer. + /// Set accessor to set only the process shared pointer from a process + /// pointer. //------------------------------------------------------------------ void SetProcessPtr(Process *process); @@ -607,8 +599,7 @@ public: void SetThreadPtr(Thread *thread); //------------------------------------------------------------------ - /// Set accessor to set only the frame shared pointer from a frame - /// pointer. + /// Set accessor to set only the frame shared pointer from a frame pointer. //------------------------------------------------------------------ void SetFramePtr(StackFrame *frame); @@ -648,8 +639,7 @@ public: void SetContext(const lldb::StackFrameSP &frame_sp); //------------------------------------------------------------------ - /// Returns true the ExecutionContext object contains a valid - /// target. + /// Returns true the ExecutionContext object contains a valid target. /// /// This function can be called after initializing an ExecutionContext /// object, and if it returns true, calls to GetTargetPtr() and @@ -658,36 +648,35 @@ public: bool HasTargetScope() const; //------------------------------------------------------------------ - /// Returns true the ExecutionContext object contains a valid - /// target and process. + /// Returns true the ExecutionContext object contains a valid target and + /// process. /// /// This function can be called after initializing an ExecutionContext /// object, and if it returns true, calls to GetTargetPtr() and - /// GetTargetRef(), GetProcessPtr(), and GetProcessRef(), do not - /// need to be checked for validity. + /// GetTargetRef(), GetProcessPtr(), and GetProcessRef(), do not need to be + /// checked for validity. //------------------------------------------------------------------ bool HasProcessScope() const; //------------------------------------------------------------------ - /// Returns true the ExecutionContext object contains a valid - /// target, process, and thread. + /// Returns true the ExecutionContext object contains a valid target, + /// process, and thread. /// /// This function can be called after initializing an ExecutionContext - /// object, and if it returns true, calls to GetTargetPtr(), - /// GetTargetRef(), GetProcessPtr(), GetProcessRef(), GetThreadPtr(), - /// and GetThreadRef() do not need to be checked for validity. + /// object, and if it returns true, calls to GetTargetPtr(), GetTargetRef(), + /// GetProcessPtr(), GetProcessRef(), GetThreadPtr(), and GetThreadRef() do + /// not need to be checked for validity. //------------------------------------------------------------------ bool HasThreadScope() const; //------------------------------------------------------------------ - /// Returns true the ExecutionContext object contains a valid - /// target, process, thread and frame. + /// Returns true the ExecutionContext object contains a valid target, + /// process, thread and frame. /// /// This function can be called after initializing an ExecutionContext - /// object, and if it returns true, calls to GetTargetPtr(), - /// GetTargetRef(), GetProcessPtr(), GetProcessRef(), GetThreadPtr(), - /// GetThreadRef(), GetFramePtr(), and GetFrameRef() do not need - /// to be checked for validity. + /// object, and if it returns true, calls to GetTargetPtr(), GetTargetRef(), + /// GetProcessPtr(), GetProcessRef(), GetThreadPtr(), GetThreadRef(), + /// GetFramePtr(), and GetFrameRef() do not need to be checked for validity. //------------------------------------------------------------------ bool HasFrameScope() const; diff --git a/lldb/include/lldb/Target/ExecutionContextScope.h b/lldb/include/lldb/Target/ExecutionContextScope.h index 36d3d9de49b..b73ca576bd8 100644 --- a/lldb/include/lldb/Target/ExecutionContextScope.h +++ b/lldb/include/lldb/Target/ExecutionContextScope.h @@ -20,22 +20,21 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ExecutionContextScope ExecutionContextScope.h -/// "lldb/Symbol/ExecutionContextScope.h" -/// @brief Inherit from this if your object can reconstruct its +/// "lldb/Symbol/ExecutionContextScope.h" Inherit from this if your object can +/// reconstruct its /// execution context. /// -/// Many objects that have pointers back to parent execution context -/// objects can inherit from this pure virtual class can reconstruct -/// their execution context without having to keep a complete -/// ExecutionContext object in the object state. Examples of these -/// objects include: Process, Thread, RegisterContext and StackFrame. +/// Many objects that have pointers back to parent execution context objects +/// can inherit from this pure virtual class can reconstruct their execution +/// context without having to keep a complete ExecutionContext object in the +/// object state. Examples of these objects include: Process, Thread, +/// RegisterContext and StackFrame. /// -/// Objects can contain a valid pointer to an instance of this so they -/// can reconstruct the execution context. +/// Objects can contain a valid pointer to an instance of this so they can +/// reconstruct the execution context. /// -/// Objects that adhere to this protocol can reconstruct enough of a -/// execution context to allow functions that take a execution contexts -/// to be called. +/// Objects that adhere to this protocol can reconstruct enough of a execution +/// context to allow functions that take a execution contexts to be called. //---------------------------------------------------------------------- class ExecutionContextScope { public: @@ -52,9 +51,9 @@ public: //------------------------------------------------------------------ /// Reconstruct the object's execution context into \a sc. /// - /// The object should fill in as much of the ExecutionContextScope as it - /// can so function calls that require a execution context can be made - /// for the given object. + /// The object should fill in as much of the ExecutionContextScope as it can + /// so function calls that require a execution context can be made for the + /// given object. /// /// @param[out] exe_ctx /// A reference to an execution context object that gets filled diff --git a/lldb/include/lldb/Target/JITLoader.h b/lldb/include/lldb/Target/JITLoader.h index 97f2a9796a8..56f1417eddb 100644 --- a/lldb/include/lldb/Target/JITLoader.h +++ b/lldb/include/lldb/Target/JITLoader.h @@ -19,21 +19,21 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class JITLoader JITLoader.h "lldb/Target/JITLoader.h" -/// @brief A plug-in interface definition class for JIT loaders. +/// A plug-in interface definition class for JIT loaders. /// -/// Plugins of this kind listen for code generated at runtime in the -/// target. They are very similar to dynamic loader, with the difference -/// that they do not have information about the target's dyld and -/// that there may be multiple JITLoader plugins per process, while -/// there is at most one DynamicLoader. +/// Plugins of this kind listen for code generated at runtime in the target. +/// They are very similar to dynamic loader, with the difference that they do +/// not have information about the target's dyld and that there may be +/// multiple JITLoader plugins per process, while there is at most one +/// DynamicLoader. //---------------------------------------------------------------------- class JITLoader : public PluginInterface { public: //------------------------------------------------------------------ /// Find a JIT loader plugin for a given process. /// - /// Scans the installed DynamicLoader plug-ins and tries to find - /// all applicable instances for the current process. + /// Scans the installed DynamicLoader plug-ins and tries to find all + /// applicable instances for the current process. /// /// @param[in] process /// The process for which to try and locate a JIT loader @@ -52,22 +52,22 @@ public: //------------------------------------------------------------------ /// Called after attaching a process. /// - /// Allow JITLoader plug-ins to execute some code after - /// attaching to a process. + /// Allow JITLoader plug-ins to execute some code after attaching to a + /// process. //------------------------------------------------------------------ virtual void DidAttach() = 0; //------------------------------------------------------------------ /// Called after launching a process. /// - /// Allow JITLoader plug-ins to execute some code after - /// the process has stopped for the first time on launch. + /// Allow JITLoader plug-ins to execute some code after the process has + /// stopped for the first time on launch. //------------------------------------------------------------------ virtual void DidLaunch() = 0; //------------------------------------------------------------------ - /// Called after a new shared object has been loaded so that it can - /// be probed for JIT entry point hooks. + /// Called after a new shared object has been loaded so that it can be + /// probed for JIT entry point hooks. //------------------------------------------------------------------ virtual void ModulesDidLoad(lldb_private::ModuleList &module_list) = 0; diff --git a/lldb/include/lldb/Target/ModuleCache.h b/lldb/include/lldb/Target/ModuleCache.h index 4959ee8ea0a..a060937e061 100644 --- a/lldb/include/lldb/Target/ModuleCache.h +++ b/lldb/include/lldb/Target/ModuleCache.h @@ -28,10 +28,10 @@ class UUID; //---------------------------------------------------------------------- /// @class ModuleCache ModuleCache.h "lldb/Target/ModuleCache.h" -/// @brief A module cache class. +/// A module cache class. /// -/// Caches locally modules that are downloaded from remote targets. -/// Each cached module maintains 2 views: +/// Caches locally modules that are downloaded from remote targets. Each +/// cached module maintains 2 views: /// - UUID view: /// /${CACHE_ROOT}/${PLATFORM_NAME}/.cache/${UUID}/${MODULE_FILENAME} /// - Sysroot view: @@ -42,7 +42,8 @@ class UUID; /// /// Example: /// UUID view : -/// /tmp/lldb/remote-linux/.cache/30C94DC6-6A1F-E951-80C3-D68D2B89E576-D5AE213C/libc.so.6 +/// /tmp/lldb/remote- +/// linux/.cache/30C94DC6-6A1F-E951-80C3-D68D2B89E576-D5AE213C/libc.so.6 /// Sysroot view: /tmp/lldb/remote-linux/ubuntu/lib/x86_64-linux-gnu/libc.so.6 //---------------------------------------------------------------------- diff --git a/lldb/include/lldb/Target/OperatingSystem.h b/lldb/include/lldb/Target/OperatingSystem.h index 24ded3f6972..fe4fdee182f 100644 --- a/lldb/include/lldb/Target/OperatingSystem.h +++ b/lldb/include/lldb/Target/OperatingSystem.h @@ -22,13 +22,13 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class OperatingSystem OperatingSystem.h "lldb/Target/OperatingSystem.h" -/// @brief A plug-in interface definition class for halted OS helpers. +/// A plug-in interface definition class for halted OS helpers. /// /// Halted OS plug-ins can be used by any process to locate and create /// OS objects, like threads, during the lifetime of a debug session. /// This is commonly used when attaching to an operating system that is -/// halted, such as when debugging over JTAG or connecting to low level -/// kernel debug services. +/// halted, such as when debugging over JTAG or connecting to low level kernel +/// debug services. //---------------------------------------------------------------------- class OperatingSystem : public PluginInterface { @@ -36,9 +36,8 @@ public: //------------------------------------------------------------------ /// Find a halted OS plugin for a given process. /// - /// Scans the installed OperatingSystem plug-ins and tries to find - /// an instance that matches the current target triple and - /// executable. + /// Scans the installed OperatingSystem plug-ins and tries to find an + /// instance that matches the current target triple and executable. /// /// @param[in] process /// The process for which to try and locate a halted OS diff --git a/lldb/include/lldb/Target/Platform.h b/lldb/include/lldb/Target/Platform.h index c3d88c4b469..62a536be10f 100644 --- a/lldb/include/lldb/Target/Platform.h +++ b/lldb/include/lldb/Target/Platform.h @@ -53,7 +53,7 @@ typedef llvm::SmallVector<lldb::addr_t, 6> MmapArgList; //---------------------------------------------------------------------- /// @class Platform Platform.h "lldb/Target/Platform.h" -/// @brief A plug-in interface definition class for debug platform that +/// A plug-in interface definition class for debug platform that /// includes many platform abilities such as: /// @li getting platform information such as supported architectures, /// supported binary file formats and more @@ -74,8 +74,8 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited from by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// from by the plug-in instance. //------------------------------------------------------------------ ~Platform() override; @@ -88,13 +88,13 @@ public: //------------------------------------------------------------------ /// Get the native host platform plug-in. /// - /// There should only be one of these for each host that LLDB runs - /// upon that should be statically compiled in and registered using - /// preprocessor macros or other similar build mechanisms in a + /// There should only be one of these for each host that LLDB runs upon that + /// should be statically compiled in and registered using preprocessor + /// macros or other similar build mechanisms in a /// PlatformSubclass::Initialize() function. /// - /// This platform will be used as the default platform when launching - /// or attaching to processes unless another platform is specified. + /// This platform will be used as the default platform when launching or + /// attaching to processes unless another platform is specified. //------------------------------------------------------------------ static lldb::PlatformSP GetHostPlatform(); @@ -123,8 +123,8 @@ public: //------------------------------------------------------------------ /// Find a platform plugin for a given process. /// - /// Scans the installed Platform plug-ins and tries to find - /// an instance that can be used for \a process + /// Scans the installed Platform plug-ins and tries to find an instance that + /// can be used for \a process /// /// @param[in] process /// The process for which to try and locate a platform @@ -138,19 +138,17 @@ public: // FindPlugin (Process *process, const ConstString &plugin_name); //------------------------------------------------------------------ - /// Set the target's executable based off of the existing - /// architecture information in \a target given a path to an - /// executable \a exe_file. + /// Set the target's executable based off of the existing architecture + /// information in \a target given a path to an executable \a exe_file. /// - /// Each platform knows the architectures that it supports and can - /// select the correct architecture slice within \a exe_file by - /// inspecting the architecture in \a target. If the target had an - /// architecture specified, then in can try and obey that request - /// and optionally fail if the architecture doesn't match up. - /// If no architecture is specified, the platform should select the - /// default architecture from \a exe_file. Any application bundles - /// or executable wrappers can also be inspected for the actual - /// application binary within the bundle that should be used. + /// Each platform knows the architectures that it supports and can select + /// the correct architecture slice within \a exe_file by inspecting the + /// architecture in \a target. If the target had an architecture specified, + /// then in can try and obey that request and optionally fail if the + /// architecture doesn't match up. If no architecture is specified, the + /// platform should select the default architecture from \a exe_file. Any + /// application bundles or executable wrappers can also be inspected for the + /// actual application binary within the bundle that should be used. /// /// @return /// Returns \b true if this Platform plug-in was able to find @@ -163,10 +161,10 @@ public: //------------------------------------------------------------------ /// Find a symbol file given a symbol file module specification. /// - /// Each platform might have tricks to find symbol files for an - /// executable given information in a symbol file ModuleSpec. Some - /// platforms might also support symbol files that are bundles and - /// know how to extract the right symbol file given a bundle. + /// Each platform might have tricks to find symbol files for an executable + /// given information in a symbol file ModuleSpec. Some platforms might also + /// support symbol files that are bundles and know how to extract the right + /// symbol file given a bundle. /// /// @param[in] target /// The target in which we are trying to resolve the symbol file. @@ -211,9 +209,8 @@ public: FileSpec &sym_file); //------------------------------------------------------------------ - /// Resolves the FileSpec to a (possibly) remote path. Remote - /// platforms must override this to resolve to a path on the remote - /// side. + /// Resolves the FileSpec to a (possibly) remote path. Remote platforms must + /// override this to resolve to a path on the remote side. //------------------------------------------------------------------ virtual bool ResolveRemotePath(const FileSpec &platform_path, FileSpec &resolved_platform_path); @@ -221,12 +218,11 @@ public: //------------------------------------------------------------------ /// Get the OS version from a connected platform. /// - /// Some platforms might not be connected to a remote platform, but - /// can figure out the OS version for a process. This is common for - /// simulator platforms that will run native programs on the current - /// host, but the simulator might be simulating a different OS. The - /// \a process parameter might be specified to help to determine - /// the OS version. + /// Some platforms might not be connected to a remote platform, but can + /// figure out the OS version for a process. This is common for simulator + /// platforms that will run native programs on the current host, but the + /// simulator might be simulating a different OS. The \a process parameter + /// might be specified to help to determine the OS version. //------------------------------------------------------------------ virtual bool GetOSVersion(uint32_t &major, uint32_t &minor, uint32_t &update, Process *process = nullptr); @@ -249,10 +245,10 @@ public: //------------------------------------------------------------------ /// Report the current status for this platform. /// - /// The returned string usually involves returning the OS version - /// (if available), and any SDK directory that might be being used - /// for local file caching, and if connected a quick blurb about - /// what this platform is connected to. + /// The returned string usually involves returning the OS version (if + /// available), and any SDK directory that might be being used for local + /// file caching, and if connected a quick blurb about what this platform is + /// connected to. //------------------------------------------------------------------ virtual void GetStatus(Stream &strm); @@ -291,8 +287,8 @@ public: //------------------------------------------------------------------ /// Locate a file for a platform. /// - /// The default implementation of this function will return the same - /// file patch in \a local_file as was in \a platform_file. + /// The default implementation of this function will return the same file + /// patch in \a local_file as was in \a platform_file. /// /// @param[in] platform_file /// The platform file path to locate and cache locally. @@ -343,8 +339,8 @@ public: virtual Status DisconnectRemote(); //------------------------------------------------------------------ - /// Get the platform's supported architectures in the order in which - /// they should be searched. + /// Get the platform's supported architectures in the order in which they + /// should be searched. /// /// @param[in] idx /// A zero based architecture index @@ -364,14 +360,14 @@ public: BreakpointSite *bp_site); //------------------------------------------------------------------ - /// Launch a new process on a platform, not necessarily for - /// debugging, it could be just for running the process. + /// Launch a new process on a platform, not necessarily for debugging, it + /// could be just for running the process. //------------------------------------------------------------------ virtual Status LaunchProcess(ProcessLaunchInfo &launch_info); //------------------------------------------------------------------ - /// Perform expansion of the command-line for this launch info - /// This can potentially involve wildcard expansion + /// Perform expansion of the command-line for this launch info This can + /// potentially involve wildcard expansion // environment variable replacement, and whatever other // argument magic the platform defines as part of its typical // user experience @@ -384,28 +380,27 @@ public: virtual Status KillProcess(const lldb::pid_t pid); //------------------------------------------------------------------ - /// Lets a platform answer if it is compatible with a given - /// architecture and the target triple contained within. + /// Lets a platform answer if it is compatible with a given architecture and + /// the target triple contained within. //------------------------------------------------------------------ virtual bool IsCompatibleArchitecture(const ArchSpec &arch, bool exact_arch_match, ArchSpec *compatible_arch_ptr); //------------------------------------------------------------------ - /// Not all platforms will support debugging a process by spawning - /// somehow halted for a debugger (specified using the - /// "eLaunchFlagDebug" launch flag) and then attaching. If your - /// platform doesn't support this, override this function and return - /// false. + /// Not all platforms will support debugging a process by spawning somehow + /// halted for a debugger (specified using the "eLaunchFlagDebug" launch + /// flag) and then attaching. If your platform doesn't support this, + /// override this function and return false. //------------------------------------------------------------------ virtual bool CanDebugProcess() { return true; } //------------------------------------------------------------------ - /// Subclasses do not need to implement this function as it uses - /// the Platform::LaunchProcess() followed by Platform::Attach (). - /// Remote platforms will want to subclass this function in order - /// to be able to intercept STDIO and possibly launch a separate - /// process that will debug the debuggee. + /// Subclasses do not need to implement this function as it uses the + /// Platform::LaunchProcess() followed by Platform::Attach (). Remote + /// platforms will want to subclass this function in order to be able to + /// intercept STDIO and possibly launch a separate process that will debug + /// the debuggee. //------------------------------------------------------------------ virtual lldb::ProcessSP DebugProcess(ProcessLaunchInfo &launch_info, Debugger &debugger, @@ -422,11 +417,11 @@ public: //------------------------------------------------------------------ /// Attach to an existing process using a process ID. /// - /// Each platform subclass needs to implement this function and - /// attempt to attach to the process with the process ID of \a pid. - /// The platform subclass should return an appropriate ProcessSP - /// subclass that is attached to the process, or an empty shared - /// pointer with an appropriate error. + /// Each platform subclass needs to implement this function and attempt to + /// attach to the process with the process ID of \a pid. The platform + /// subclass should return an appropriate ProcessSP subclass that is + /// attached to the process, or an empty shared pointer with an appropriate + /// error. /// /// @param[in] pid /// The process ID that we should attempt to attach to. @@ -447,12 +442,11 @@ public: //------------------------------------------------------------------ /// Attach to an existing process by process name. /// - /// This function is not meant to be overridden by Process - /// subclasses. It will first call - /// Process::WillAttach (const char *) and if that returns \b - /// true, Process::DoAttach (const char *) will be called to - /// actually do the attach. If DoAttach returns \b true, then - /// Process::DidAttach() will be called. + /// This function is not meant to be overridden by Process subclasses. It + /// will first call Process::WillAttach (const char *) and if that returns + /// \b true, Process::DoAttach (const char *) will be called to actually do + /// the attach. If DoAttach returns \b true, then Process::DidAttach() will + /// be called. /// /// @param[in] process_name /// A process name to match against the current process list. @@ -513,9 +507,9 @@ public: } //--------------------------------------------------------------------------- - /// If the triple contains not specify the vendor, os, and environment parts, - /// we "augment" these using information from the platform and return the - /// resulting ArchSpec object. + /// If the triple contains not specify the vendor, os, and environment + /// parts, we "augment" these using information from the platform and return + /// the resulting ArchSpec object. //--------------------------------------------------------------------------- ArchSpec GetAugmentedArchSpec(llvm::StringRef triple); @@ -605,11 +599,11 @@ public: //---------------------------------------------------------------------- /// Install a file or directory to the remote system. /// - /// Install is similar to Platform::PutFile(), but it differs in that if - /// an application/framework/shared library is installed on a remote - /// platform and the remote platform requires something to be done to - /// register the application/framework/shared library, then this extra - /// registration can be done. + /// Install is similar to Platform::PutFile(), but it differs in that if an + /// application/framework/shared library is installed on a remote platform + /// and the remote platform requires something to be done to register the + /// application/framework/shared library, then this extra registration can + /// be done. /// /// @param[in] src /// The source file/directory to install on the remote system. @@ -705,12 +699,12 @@ public: //------------------------------------------------------------------ /// Locate a queue name given a thread's qaddr /// - /// On a system using libdispatch ("Grand Central Dispatch") style - /// queues, a thread may be associated with a GCD queue or not, - /// and a queue may be associated with multiple threads. - /// The process/thread must provide a way to find the "dispatch_qaddr" - /// for each thread, and from that dispatch_qaddr this Platform method - /// will locate the queue name and provide that. + /// On a system using libdispatch ("Grand Central Dispatch") style queues, a + /// thread may be associated with a GCD queue or not, and a queue may be + /// associated with multiple threads. The process/thread must provide a way + /// to find the "dispatch_qaddr" for each thread, and from that + /// dispatch_qaddr this Platform method will locate the queue name and + /// provide that. /// /// @param[in] process /// A process is required for reading memory. @@ -731,12 +725,12 @@ public: //------------------------------------------------------------------ /// Locate a queue ID given a thread's qaddr /// - /// On a system using libdispatch ("Grand Central Dispatch") style - /// queues, a thread may be associated with a GCD queue or not, - /// and a queue may be associated with multiple threads. - /// The process/thread must provide a way to find the "dispatch_qaddr" - /// for each thread, and from that dispatch_qaddr this Platform method - /// will locate the queue ID and provide that. + /// On a system using libdispatch ("Grand Central Dispatch") style queues, a + /// thread may be associated with a GCD queue or not, and a queue may be + /// associated with multiple threads. The process/thread must provide a way + /// to find the "dispatch_qaddr" for each thread, and from that + /// dispatch_qaddr this Platform method will locate the queue ID and provide + /// that. /// /// @param[in] process /// A process is required for reading memory. @@ -756,12 +750,12 @@ public: //------------------------------------------------------------------ /// Provide a list of trap handler function names for this platform /// - /// The unwinder needs to treat trap handlers specially -- the stack - /// frame may not be aligned correctly for a trap handler (the kernel - /// often won't perturb the stack pointer, or won't re-align it properly, - /// in the process of calling the handler) and the frame above the handler - /// needs to be treated by the unwinder's "frame 0" rules instead of its - /// "middle of the stack frame" rules. + /// The unwinder needs to treat trap handlers specially -- the stack frame + /// may not be aligned correctly for a trap handler (the kernel often won't + /// perturb the stack pointer, or won't re-align it properly, in the process + /// of calling the handler) and the frame above the handler needs to be + /// treated by the unwinder's "frame 0" rules instead of its "middle of the + /// stack frame" rules. /// /// In a user process debugging scenario, the list of trap handlers is /// typically just "_sigtramp". @@ -777,12 +771,11 @@ public: virtual const std::vector<ConstString> &GetTrapHandlerSymbolNames(); //------------------------------------------------------------------ - /// Find a support executable that may not live within in the - /// standard locations related to LLDB. + /// Find a support executable that may not live within in the standard + /// locations related to LLDB. /// - /// Executable might exist within the Platform SDK directories, or - /// in standard tool directories within the current IDE that is - /// running LLDB. + /// Executable might exist within the Platform SDK directories, or in + /// standard tool directories within the current IDE that is running LLDB. /// /// @param[in] basename /// The basename of the executable to locate in the current @@ -796,19 +789,17 @@ public: //------------------------------------------------------------------ /// Allow the platform to set preferred memory cache line size. If non-zero - /// (and the user - /// has not set cache line size explicitly), this value will be used as the - /// cache line - /// size for memory reads. + /// (and the user has not set cache line size explicitly), this value will + /// be used as the cache line size for memory reads. //------------------------------------------------------------------ virtual uint32_t GetDefaultMemoryCacheLineSize() { return 0; } //------------------------------------------------------------------ /// Load a shared library into this process. /// - /// Try and load a shared library into the current process. This - /// call might fail in the dynamic loader plug-in says it isn't safe - /// to try and load shared libraries at the moment. + /// Try and load a shared library into the current process. This call might + /// fail in the dynamic loader plug-in says it isn't safe to try and load + /// shared libraries at the moment. /// /// @param[in] process /// The process to load the image. @@ -851,8 +842,8 @@ public: //------------------------------------------------------------------ /// Connect to all processes waiting for a debugger to attach /// - /// If the platform have a list of processes waiting for a debugger - /// to connect to them then connect to all of these pending processes. + /// If the platform have a list of processes waiting for a debugger to + /// connect to them then connect to all of these pending processes. /// /// @param[in] debugger /// The debugger used for the connect. @@ -910,14 +901,14 @@ protected: //------------------------------------------------------------------ /// Ask the Platform subclass to fill in the list of trap handler names /// - /// For most Unix user process environments, this will be a single - /// function name, _sigtramp. More specialized environments may have - /// additional handler names. The unwinder code needs to know when a - /// trap handler is on the stack because the unwind rules for the frame - /// that caused the trap are different. + /// For most Unix user process environments, this will be a single function + /// name, _sigtramp. More specialized environments may have additional + /// handler names. The unwinder code needs to know when a trap handler is + /// on the stack because the unwind rules for the frame that caused the trap + /// are different. /// - /// The base class Platform ivar m_trap_handlers should be updated by - /// the Platform subclass when this method is called. If there are no + /// The base class Platform ivar m_trap_handlers should be updated by the + /// Platform subclass when this method is called. If there are no /// predefined trap handlers, this method may be a no-op. //------------------------------------------------------------------ virtual void CalculateTrapHandlerSymbolNames() = 0; @@ -1050,11 +1041,10 @@ public: //------------------------------------------------------------------ /// Select the active platform. /// - /// In order to debug remotely, other platform's can be remotely - /// connected to and set as the selected platform for any subsequent - /// debugging. This allows connection to remote targets and allows - /// the ability to discover process info, launch and attach to remote - /// processes. + /// In order to debug remotely, other platform's can be remotely connected + /// to and set as the selected platform for any subsequent debugging. This + /// allows connection to remote targets and allows the ability to discover + /// process info, launch and attach to remote processes. //------------------------------------------------------------------ lldb::PlatformSP GetSelectedPlatform() { std::lock_guard<std::recursive_mutex> guard(m_mutex); diff --git a/lldb/include/lldb/Target/Process.h b/lldb/include/lldb/Target/Process.h index a55e6cbcbdb..8f2680c4400 100644 --- a/lldb/include/lldb/Target/Process.h +++ b/lldb/include/lldb/Target/Process.h @@ -498,7 +498,7 @@ inline bool operator!=(const ProcessModID &lhs, const ProcessModID &rhs) { //---------------------------------------------------------------------- /// @class Process Process.h "lldb/Target/Process.h" -/// @brief A plug-in interface definition class for debugging a process. +/// A plug-in interface definition class for debugging a process. //---------------------------------------------------------------------- class Process : public std::enable_shared_from_this<Process>, public ProcessProperties, @@ -559,8 +559,8 @@ public: /// A notification structure that can be used by clients to listen /// for changes in a process's lifetime. /// -/// @see RegisterNotificationCallbacks (const Notifications&) -/// @see UnregisterNotificationCallbacks (const Notifications&) +/// @see RegisterNotificationCallbacks (const Notifications&) @see +/// UnregisterNotificationCallbacks (const Notifications&) //------------------------------------------------------------------ #ifndef SWIG typedef struct { @@ -656,8 +656,8 @@ public: Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp); //------------------------------------------------------------------ - /// Construct with a shared pointer to a target, the Process listener, - /// and the appropriate UnixSignalsSP for the process. + /// Construct with a shared pointer to a target, the Process listener, and + /// the appropriate UnixSignalsSP for the process. //------------------------------------------------------------------ Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp, const lldb::UnixSignalsSP &unix_signals_sp); @@ -665,8 +665,8 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited from by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// from by the plug-in instance. //------------------------------------------------------------------ ~Process() override; @@ -677,12 +677,12 @@ public: static const ProcessPropertiesSP &GetGlobalProperties(); //------------------------------------------------------------------ - /// Find a Process plug-in that can debug \a module using the - /// currently selected architecture. + /// Find a Process plug-in that can debug \a module using the currently + /// selected architecture. /// - /// Scans all loaded plug-in interfaces that implement versions of - /// the Process plug-in interface and returns the first instance - /// that can debug the file. + /// Scans all loaded plug-in interfaces that implement versions of the + /// Process plug-in interface and returns the first instance that can debug + /// the file. /// /// @param[in] module_sp /// The module shared pointer that this process will debug. @@ -703,11 +703,10 @@ public: /// Static function that can be used with the \b host function /// Host::StartMonitoringChildProcess (). /// - /// This function can be used by lldb_private::Process subclasses - /// when they want to watch for a local process and have its exit - /// status automatically set when the host child process exits. - /// Subclasses should call Host::StartMonitoringChildProcess () - /// with: + /// This function can be used by lldb_private::Process subclasses when they + /// want to watch for a local process and have its exit status automatically + /// set when the host child process exits. Subclasses should call + /// Host::StartMonitoringChildProcess () with: /// callback = Process::SetHostProcessExitStatus /// pid = Process::GetID() /// monitor_signals = false @@ -727,9 +726,9 @@ public: //------------------------------------------------------------------ /// Check if a plug-in instance can debug the file in \a module. /// - /// Each plug-in is given a chance to say whether it can debug - /// the file in \a module. If the Process plug-in instance can - /// debug a file on the current system, it should return \b true. + /// Each plug-in is given a chance to say whether it can debug the file in + /// \a module. If the Process plug-in instance can debug a file on the + /// current system, it should return \b true. /// /// @return /// Returns \b true if this Process plug-in instance can @@ -741,8 +740,8 @@ public: //------------------------------------------------------------------ /// This object is about to be destroyed, do any necessary cleanup. /// - /// Subclasses that override this method should always call this - /// superclass method. + /// Subclasses that override this method should always call this superclass + /// method. //------------------------------------------------------------------ virtual void Finalize(); @@ -756,8 +755,8 @@ public: bool IsValid() const { return !m_finalize_called; } //------------------------------------------------------------------ - /// Return a multi-word command object that can be used to expose - /// plug-in specific commands. + /// Return a multi-word command object that can be used to expose plug-in + /// specific commands. /// /// This object will be used to resolve plug-in commands and can be /// triggered by a call to: @@ -774,16 +773,15 @@ public: //------------------------------------------------------------------ /// Launch a new process. /// - /// Launch a new process by spawning a new process using the - /// target object's executable module's file as the file to launch. + /// Launch a new process by spawning a new process using the target object's + /// executable module's file as the file to launch. /// - /// This function is not meant to be overridden by Process - /// subclasses. It will first call Process::WillLaunch (Module *) - /// and if that returns \b true, Process::DoLaunch (Module*, - /// char const *[],char const *[],const char *,const char *, - /// const char *) will be called to actually do the launching. If - /// DoLaunch returns \b true, then Process::DidLaunch() will be - /// called. + /// This function is not meant to be overridden by Process subclasses. It + /// will first call Process::WillLaunch (Module *) and if that returns \b + /// true, Process::DoLaunch (Module*, char const *[],char const *[],const + /// char *,const char *, const char *) will be called to actually do the + /// launching. If DoLaunch returns \b true, then Process::DidLaunch() will + /// be called. /// /// @param[in] launch_info /// Details regarding the environment, STDIN/STDOUT/STDERR @@ -822,12 +820,12 @@ public: // We are postponing designing this till we have at least a second use case. //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Set the cached UtilityFunction that assists in loading binary - /// images into the process. + /// Set the cached UtilityFunction that assists in loading binary images + /// into the process. /// /// This UtilityFunction is maintained in the Process since the Platforms - /// don't track the lifespan of the Targets/Processes that use them. - /// But it is not intended to be comprehended by the Process, it's up to the + /// don't track the lifespan of the Targets/Processes that use them. But + /// it is not intended to be comprehended by the Process, it's up to the /// Platform that set it to do it right. /// /// @param[in] utility_func_up @@ -839,8 +837,8 @@ public: utility_func_up); //------------------------------------------------------------------ - /// Get the cached UtilityFunction that assists in loading binary - /// images into the process. + /// Get the cached UtilityFunction that assists in loading binary images + /// into the process. /// /// @param[in] platform /// The platform fetching the UtilityFunction. @@ -854,11 +852,11 @@ public: //------------------------------------------------------------------ /// Get the dynamic loader plug-in for this process. /// - /// The default action is to let the DynamicLoader plug-ins check - /// the main executable and the DynamicLoader will select itself - /// automatically. Subclasses can override this if inspecting the - /// executable is not desired, or if Process subclasses can only - /// use a specific DynamicLoader plug-in. + /// The default action is to let the DynamicLoader plug-ins check the main + /// executable and the DynamicLoader will select itself automatically. + /// Subclasses can override this if inspecting the executable is not + /// desired, or if Process subclasses can only use a specific DynamicLoader + /// plug-in. //------------------------------------------------------------------ virtual DynamicLoader *GetDynamicLoader(); @@ -873,11 +871,11 @@ public: virtual const lldb::DataBufferSP GetAuxvData(); //------------------------------------------------------------------ - /// Sometimes processes know how to retrieve and load shared libraries. - /// This is normally done by DynamicLoader plug-ins, but sometimes the - /// connection to the process allows retrieving this information. The - /// dynamic loader plug-ins can use this function if they can't - /// determine the current shared library load state. + /// Sometimes processes know how to retrieve and load shared libraries. This + /// is normally done by DynamicLoader plug-ins, but sometimes the connection + /// to the process allows retrieving this information. The dynamic loader + /// plug-ins can use this function if they can't determine the current + /// shared library load state. /// /// @return /// The number of shared libraries that were loaded @@ -902,11 +900,10 @@ public: //------------------------------------------------------------------ /// Attach to an existing process using the process attach info. /// - /// This function is not meant to be overridden by Process - /// subclasses. It will first call WillAttach (lldb::pid_t) - /// or WillAttach (const char *), and if that returns \b - /// true, DoAttach (lldb::pid_t) or DoAttach (const char *) will - /// be called to actually do the attach. If DoAttach returns \b + /// This function is not meant to be overridden by Process subclasses. It + /// will first call WillAttach (lldb::pid_t) or WillAttach (const char *), + /// and if that returns \b true, DoAttach (lldb::pid_t) or DoAttach (const + /// char *) will be called to actually do the attach. If DoAttach returns \b /// true, then Process::DidAttach() will be called. /// /// @param[in] pid @@ -941,12 +938,11 @@ public: //------------------------------------------------------------------ /// Get the image information address for the current process. /// - /// Some runtimes have system functions that can help dynamic - /// loaders locate the dynamic loader information needed to observe - /// shared libraries being loaded or unloaded. This function is - /// in the Process interface (as opposed to the DynamicLoader - /// interface) to ensure that remote debugging can take advantage of - /// this functionality. + /// Some runtimes have system functions that can help dynamic loaders locate + /// the dynamic loader information needed to observe shared libraries being + /// loaded or unloaded. This function is in the Process interface (as + /// opposed to the DynamicLoader interface) to ensure that remote debugging + /// can take advantage of this functionality. /// /// @return /// The address of the dynamic loader information, or @@ -958,17 +954,16 @@ public: //------------------------------------------------------------------ /// Called when the process is about to broadcast a public stop. /// - /// There are public and private stops. Private stops are when the - /// process is doing things like stepping and the client doesn't - /// need to know about starts and stop that implement a thread plan. - /// Single stepping over a source line in code might end up being - /// implemented by one or more process starts and stops. Public stops - /// are when clients will be notified that the process is stopped. - /// These events typically trigger UI updates (thread stack frames to - /// be displayed, variables to be displayed, and more). This function - /// can be overriden and allows process subclasses to do something - /// before the eBroadcastBitStateChanged event is sent to public - /// clients. + /// There are public and private stops. Private stops are when the process + /// is doing things like stepping and the client doesn't need to know about + /// starts and stop that implement a thread plan. Single stepping over a + /// source line in code might end up being implemented by one or more + /// process starts and stops. Public stops are when clients will be notified + /// that the process is stopped. These events typically trigger UI updates + /// (thread stack frames to be displayed, variables to be displayed, and + /// more). This function can be overriden and allows process subclasses to + /// do something before the eBroadcastBitStateChanged event is sent to + /// public clients. //------------------------------------------------------------------ virtual void WillPublicStop() {} @@ -991,8 +986,8 @@ public: //------------------------------------------------------------------ /// Unregister for process and thread notifications. /// -/// Clients can unregister notification callbacks by passing a copy of -/// the original baton and callbacks in \a callbacks. +/// Clients can unregister notification callbacks by passing a copy of the +/// original baton and callbacks in \a callbacks. /// /// @param[in] callbacks /// A structure that contains the notification baton and @@ -1012,25 +1007,24 @@ public: // Built in Process Control functions //================================================================== //------------------------------------------------------------------ - /// Resumes all of a process's threads as configured using the - /// Thread run control functions. + /// Resumes all of a process's threads as configured using the Thread run + /// control functions. /// - /// Threads for a process should be updated with one of the run - /// control actions (resume, step, or suspend) that they should take - /// when the process is resumed. If no run control action is given - /// to a thread it will be resumed by default. + /// Threads for a process should be updated with one of the run control + /// actions (resume, step, or suspend) that they should take when the + /// process is resumed. If no run control action is given to a thread it + /// will be resumed by default. /// - /// This function is not meant to be overridden by Process - /// subclasses. This function will take care of disabling any - /// breakpoints that threads may be stopped at, single stepping, and - /// re-enabling breakpoints, and enabling the basic flow control - /// that the plug-in instances need not worry about. + /// This function is not meant to be overridden by Process subclasses. This + /// function will take care of disabling any breakpoints that threads may be + /// stopped at, single stepping, and re-enabling breakpoints, and enabling + /// the basic flow control that the plug-in instances need not worry about. /// - /// N.B. This function also sets the Write side of the Run Lock, - /// which is unset when the corresponding stop event is pulled off - /// the Public Event Queue. If you need to resume the process without - /// setting the Run Lock, use PrivateResume (though you should only do - /// that from inside the Process class. + /// N.B. This function also sets the Write side of the Run Lock, which is + /// unset when the corresponding stop event is pulled off the Public Event + /// Queue. If you need to resume the process without setting the Run Lock, + /// use PrivateResume (though you should only do that from inside the + /// Process class. /// /// @return /// Returns an error object. @@ -1046,11 +1040,10 @@ public: //------------------------------------------------------------------ /// Halts a running process. /// - /// This function is not meant to be overridden by Process - /// subclasses. - /// If the process is successfully halted, a eStateStopped - /// process event with GetInterrupted will be broadcast. If false, we will - /// halt the process with no events generated by the halt. + /// This function is not meant to be overridden by Process subclasses. If + /// the process is successfully halted, a eStateStopped process event with + /// GetInterrupted will be broadcast. If false, we will halt the process + /// with no events generated by the halt. /// /// @param[in] clear_thread_plans /// If true, when the process stops, clear all thread plans. @@ -1068,8 +1061,7 @@ public: //------------------------------------------------------------------ /// Detaches from a running or stopped process. /// - /// This function is not meant to be overridden by Process - /// subclasses. + /// This function is not meant to be overridden by Process subclasses. /// /// @param[in] keep_stopped /// If true, don't resume the process on detach. @@ -1080,11 +1072,10 @@ public: Status Detach(bool keep_stopped); //------------------------------------------------------------------ - /// Kills the process and shuts down all threads that were spawned - /// to track and monitor the process. + /// Kills the process and shuts down all threads that were spawned to track + /// and monitor the process. /// - /// This function is not meant to be overridden by Process - /// subclasses. + /// This function is not meant to be overridden by Process subclasses. /// /// @param[in] force_kill /// Whether lldb should force a kill (instead of a detach) from @@ -1102,8 +1093,7 @@ public: //------------------------------------------------------------------ /// Sends a process a UNIX signal \a signal. /// - /// This function is not meant to be overridden by Process - /// subclasses. + /// This function is not meant to be overridden by Process subclasses. /// /// @return /// Returns an error object. @@ -1121,8 +1111,7 @@ public: //------------------------------------------------------------------ /// Called before attaching to a process. /// - /// Allow Process plug-ins to execute some code before attaching a - /// process. + /// Allow Process plug-ins to execute some code before attaching a process. /// /// @return /// Returns an error object. @@ -1132,8 +1121,7 @@ public: //------------------------------------------------------------------ /// Called before attaching to a process. /// - /// Allow Process plug-ins to execute some code before attaching a - /// process. + /// Allow Process plug-ins to execute some code before attaching a process. /// /// @return /// Returns an error object. @@ -1218,33 +1206,31 @@ public: /// If you can figure out the process architecture after attach, fill it /// in here. /// - /// Allow Process plug-ins to execute some code after attaching to - /// a process. + /// Allow Process plug-ins to execute some code after attaching to a + /// process. //------------------------------------------------------------------ virtual void DidAttach(ArchSpec &process_arch) { process_arch.Clear(); } //------------------------------------------------------------------ /// Called after a process re-execs itself. /// - /// Allow Process plug-ins to execute some code after a process has - /// exec'ed itself. Subclasses typically should override DoDidExec() - /// as the lldb_private::Process class needs to remove its dynamic - /// loader, runtime, ABI and other plug-ins, as well as unload all - /// shared libraries. + /// Allow Process plug-ins to execute some code after a process has exec'ed + /// itself. Subclasses typically should override DoDidExec() as the + /// lldb_private::Process class needs to remove its dynamic loader, runtime, + /// ABI and other plug-ins, as well as unload all shared libraries. //------------------------------------------------------------------ virtual void DidExec(); //------------------------------------------------------------------ - /// Subclasses of Process should implement this function if they - /// need to do anything after a process exec's itself. + /// Subclasses of Process should implement this function if they need to do + /// anything after a process exec's itself. //------------------------------------------------------------------ virtual void DoDidExec() {} //------------------------------------------------------------------ /// Called before launching to a process. /// - /// Allow Process plug-ins to execute some code before launching a - /// process. + /// Allow Process plug-ins to execute some code before launching a process. /// /// @return /// Returns an error object. @@ -1254,9 +1240,9 @@ public: //------------------------------------------------------------------ /// Launch a new process. /// - /// Launch a new process by spawning a new process using - /// \a exe_module's file as the file to launch. Launch details are - /// provided in \a launch_info. + /// Launch a new process by spawning a new process using \a exe_module's + /// file as the file to launch. Launch details are provided in \a + /// launch_info. /// /// @param[in] exe_module /// The module from which to extract the file specification and @@ -1281,16 +1267,14 @@ public: //------------------------------------------------------------------ /// Called after launching a process. /// - /// Allow Process plug-ins to execute some code after launching - /// a process. + /// Allow Process plug-ins to execute some code after launching a process. //------------------------------------------------------------------ virtual void DidLaunch() {} //------------------------------------------------------------------ /// Called before resuming to a process. /// - /// Allow Process plug-ins to execute some code before resuming a - /// process. + /// Allow Process plug-ins to execute some code before resuming a process. /// /// @return /// Returns an error object. @@ -1298,13 +1282,13 @@ public: virtual Status WillResume() { return Status(); } //------------------------------------------------------------------ - /// Resumes all of a process's threads as configured using the - /// Thread run control functions. + /// Resumes all of a process's threads as configured using the Thread run + /// control functions. /// - /// Threads for a process should be updated with one of the run - /// control actions (resume, step, or suspend) that they should take - /// when the process is resumed. If no run control action is given - /// to a thread it will be resumed by default. + /// Threads for a process should be updated with one of the run control + /// actions (resume, step, or suspend) that they should take when the + /// process is resumed. If no run control action is given to a thread it + /// will be resumed by default. /// /// @return /// Returns \b true if the process successfully resumes using @@ -1325,16 +1309,14 @@ public: //------------------------------------------------------------------ /// Called after resuming a process. /// - /// Allow Process plug-ins to execute some code after resuming - /// a process. + /// Allow Process plug-ins to execute some code after resuming a process. //------------------------------------------------------------------ virtual void DidResume() {} //------------------------------------------------------------------ /// Called before halting to a process. /// - /// Allow Process plug-ins to execute some code before halting a - /// process. + /// Allow Process plug-ins to execute some code before halting a process. /// /// @return /// Returns an error object. @@ -1345,13 +1327,10 @@ public: /// Halts a running process. /// /// DoHalt must produce one and only one stop StateChanged event if it - /// actually - /// stops the process. If the stop happens through some natural event (for - /// instance a SIGSTOP), then forwarding that event will do. Otherwise, you - /// must - /// generate the event manually. This function is called from the context of - /// the - /// private state thread. + /// actually stops the process. If the stop happens through some natural + /// event (for instance a SIGSTOP), then forwarding that event will do. + /// Otherwise, you must generate the event manually. This function is called + /// from the context of the private state thread. /// /// @param[out] caused_stop /// If true, then this Halt caused the stop, otherwise, the @@ -1372,16 +1351,15 @@ public: //------------------------------------------------------------------ /// Called after halting a process. /// - /// Allow Process plug-ins to execute some code after halting - /// a process. + /// Allow Process plug-ins to execute some code after halting a process. //------------------------------------------------------------------ virtual void DidHalt() {} //------------------------------------------------------------------ /// Called before detaching from a process. /// - /// Allow Process plug-ins to execute some code before detaching - /// from a process. + /// Allow Process plug-ins to execute some code before detaching from a + /// process. /// /// @return /// Returns an error object. @@ -1406,8 +1384,8 @@ public: //------------------------------------------------------------------ /// Called after detaching from a process. /// - /// Allow Process plug-ins to execute some code after detaching - /// from a process. + /// Allow Process plug-ins to execute some code after detaching from a + /// process. //------------------------------------------------------------------ virtual void DidDetach() {} @@ -1416,8 +1394,8 @@ public: //------------------------------------------------------------------ /// Called before sending a signal to a process. /// - /// Allow Process plug-ins to execute some code before sending a - /// signal to a process. + /// Allow Process plug-ins to execute some code before sending a signal to a + /// process. /// /// @return /// Returns no error if it is safe to proceed with a call to @@ -1451,8 +1429,8 @@ public: //------------------------------------------------------------------ /// Called after sending a signal to a process. /// - /// Allow Process plug-ins to execute some code after sending a - /// signal to a process. + /// Allow Process plug-ins to execute some code after sending a signal to a + /// process. //------------------------------------------------------------------ virtual void DidSignal() {} @@ -1462,24 +1440,22 @@ public: /// event is taken from the queue... /// /// This callback is called as the event - /// is about to be queued up to allow Process plug-ins to execute - /// some code prior to clients being notified that a process was - /// stopped. Common operations include updating the thread list, - /// invalidating any thread state (registers, stack, etc) prior to - /// letting the notification go out. + /// is about to be queued up to allow Process plug-ins to execute some code + /// prior to clients being notified that a process was stopped. Common + /// operations include updating the thread list, invalidating any thread + /// state (registers, stack, etc) prior to letting the notification go out. /// //------------------------------------------------------------------ virtual void RefreshStateAfterStop() = 0; //------------------------------------------------------------------ - /// Sometimes the connection to a process can detect the host OS - /// version that the process is running on. The current platform - /// should be checked first in case the platform is connected, but - /// clients can fall back onto this function if the platform fails - /// to identify the host OS version. The platform should be checked - /// first in case you are running a simulator platform that might - /// itself be running natively, but have different heuristics for - /// figuring out which OS is is emulating. + /// Sometimes the connection to a process can detect the host OS version + /// that the process is running on. The current platform should be checked + /// first in case the platform is connected, but clients can fall back onto + /// this function if the platform fails to identify the host OS version. The + /// platform should be checked first in case you are running a simulator + /// platform that might itself be running natively, but have different + /// heuristics for figuring out which OS is is emulating. /// /// @param[out] major /// The major OS version, or UINT32_MAX if it can't be determined @@ -1523,12 +1499,12 @@ public: //------------------------------------------------------------------ /// Flush all data in the process. /// - /// Flush the memory caches, all threads, and any other cached data - /// in the process. + /// Flush the memory caches, all threads, and any other cached data in the + /// process. /// - /// This function can be called after a world changing event like - /// adding a new symbol file, or after the process makes a large - /// context switch (from boot ROM to booted into an OS). + /// This function can be called after a world changing event like adding a + /// new symbol file, or after the process makes a large context switch (from + /// boot ROM to booted into an OS). //------------------------------------------------------------------ void Flush(); @@ -1568,15 +1544,16 @@ public: //------------------------------------------------------------------ /// Retrieve the list of shared libraries that are loaded for this process - /// This method is used on pre-macOS 10.12, pre-iOS 10, pre-tvOS 10, - /// pre-watchOS 3 systems. The following two methods are for newer versions - /// of those OSes. + /// This method is used on pre-macOS 10.12, pre-iOS 10, pre-tvOS 10, pre- + /// watchOS 3 systems. The following two methods are for newer versions of + /// those OSes. /// /// For certain platforms, the time it takes for the DynamicLoader plugin to /// read all of the shared libraries out of memory over a slow communication /// channel may be too long. In that instance, the gdb-remote stub may be - /// able to retrieve the necessary information about the solibs out of memory - /// and return a concise summary sufficient for the DynamicLoader plugin. + /// able to retrieve the necessary information about the solibs out of + /// memory and return a concise summary sufficient for the DynamicLoader + /// plugin. /// /// @param [in] image_list_address /// The address where the table of shared libraries is stored in memory, @@ -1626,11 +1603,11 @@ public: } //------------------------------------------------------------------ - /// Print a user-visible warning about a module being built with optimization + /// Print a user-visible warning about a module being built with + /// optimization /// - /// Prints a async warning message to the user one time per Module - /// where a function is found that was compiled with optimization, per - /// Process. + /// Prints a async warning message to the user one time per Module where a + /// function is found that was compiled with optimization, per Process. /// /// @param [in] sc /// A SymbolContext with eSymbolContextFunction and eSymbolContextModule @@ -1690,13 +1667,12 @@ public: //------------------------------------------------------------------ /// Set accessor for the process exit status (return code). /// - /// Sometimes a child exits and the exit can be detected by global - /// functions (signal handler for SIGCHLD for example). This - /// accessor allows the exit status to be set from an external - /// source. + /// Sometimes a child exits and the exit can be detected by global functions + /// (signal handler for SIGCHLD for example). This accessor allows the exit + /// status to be set from an external source. /// - /// Setting this will cause a eStateExited event to be posted to - /// the process event queue. + /// Setting this will cause a eStateExited event to be posted to the process + /// event queue. /// /// @param[in] exit_status /// The value for the process's return code. @@ -1715,11 +1691,10 @@ public: virtual bool IsAlive(); //------------------------------------------------------------------ - /// Before lldb detaches from a process, it warns the user that they are about - /// to lose their debug session. - /// In some cases, this warning doesn't need to be emitted -- for instance, - /// with core file debugging where - /// the user can reconstruct the "state" by simply re-running the debugger on + /// Before lldb detaches from a process, it warns the user that they are + /// about to lose their debug session. In some cases, this warning doesn't + /// need to be emitted -- for instance, with core file debugging where the + /// user can reconstruct the "state" by simply re-running the debugger on /// the core file. /// /// @return @@ -1730,10 +1705,9 @@ public: //------------------------------------------------------------------ /// Actually do the reading of memory from a process. /// - /// Subclasses must override this function and can return fewer - /// bytes than requested when memory requests are too large. This - /// class will break up the memory requests and keep advancing the - /// arguments along as needed. + /// Subclasses must override this function and can return fewer bytes than + /// requested when memory requests are too large. This class will break up + /// the memory requests and keep advancing the arguments along as needed. /// /// @param[in] vm_addr /// A virtual load address that indicates where to start reading @@ -1755,13 +1729,12 @@ public: //------------------------------------------------------------------ /// Read of memory from a process. /// - /// This function will read memory from the current process's - /// address space and remove any traps that may have been inserted - /// into the memory. + /// This function will read memory from the current process's address space + /// and remove any traps that may have been inserted into the memory. /// - /// This function is not meant to be overridden by Process - /// subclasses, the subclasses should implement - /// Process::DoReadMemory (lldb::addr_t, size_t, void *). + /// This function is not meant to be overridden by Process subclasses, the + /// subclasses should implement Process::DoReadMemory (lldb::addr_t, size_t, + /// void *). /// /// @param[in] vm_addr /// A virtual load address that indicates where to start reading @@ -1787,12 +1760,12 @@ public: //------------------------------------------------------------------ /// Read a NULL terminated string from memory /// - /// This function will read a cache page at a time until a NULL - /// string terminator is found. It will stop reading if an aligned - /// sequence of NULL termination \a type_width bytes is not found - /// before reading \a cstr_max_len bytes. The results are always - /// guaranteed to be NULL terminated, and that no more than - /// (max_bytes - type_width) bytes will be read. + /// This function will read a cache page at a time until a NULL string + /// terminator is found. It will stop reading if an aligned sequence of NULL + /// termination \a type_width bytes is not found before reading \a + /// cstr_max_len bytes. The results are always guaranteed to be NULL + /// terminated, and that no more than (max_bytes - type_width) bytes will be + /// read. /// /// @param[in] vm_addr /// The virtual load address to start the memory read. @@ -1821,9 +1794,9 @@ public: /// /// This function will read a cache page at a time until the NULL /// C string terminator is found. It will stop reading if the NULL - /// termination byte isn't found before reading \a cstr_max_len - /// bytes, and the results are always guaranteed to be NULL - /// terminated (at most cstr_max_len - 1 bytes will be read). + /// termination byte isn't found before reading \a cstr_max_len bytes, and + /// the results are always guaranteed to be NULL terminated (at most + /// cstr_max_len - 1 bytes will be read). //------------------------------------------------------------------ size_t ReadCStringFromMemory(lldb::addr_t vm_addr, char *cstr, size_t cstr_max_len, Status &error); @@ -1835,8 +1808,8 @@ public: Status &error); //------------------------------------------------------------------ - /// Reads an unsigned integer of the specified byte size from - /// process memory. + /// Reads an unsigned integer of the specified byte size from process + /// memory. /// /// @param[in] load_addr /// A load address of the integer to read. @@ -1904,13 +1877,12 @@ public: //------------------------------------------------------------------ /// Write all or part of a scalar value to memory. /// - /// The value contained in \a scalar will be swapped to match the - /// byte order of the process that is being debugged. If \a size is - /// less than the size of scalar, the least significant \a size bytes - /// from scalar will be written. If \a size is larger than the byte - /// size of scalar, then the extra space will be padded with zeros - /// and the scalar value will be placed in the least significant - /// bytes in memory. + /// The value contained in \a scalar will be swapped to match the byte order + /// of the process that is being debugged. If \a size is less than the size + /// of scalar, the least significant \a size bytes from scalar will be + /// written. If \a size is larger than the byte size of scalar, then the + /// extra space will be padded with zeros and the scalar value will be + /// placed in the least significant bytes in memory. /// /// @param[in] vm_addr /// A virtual load address that indicates where to start writing @@ -1943,13 +1915,13 @@ public: //------------------------------------------------------------------ /// Write memory to a process. /// - /// This function will write memory to the current process's - /// address space and maintain any traps that might be present due - /// to software breakpoints. + /// This function will write memory to the current process's address space + /// and maintain any traps that might be present due to software + /// breakpoints. /// - /// This function is not meant to be overridden by Process - /// subclasses, the subclasses should implement - /// Process::DoWriteMemory (lldb::addr_t, size_t, void *). + /// This function is not meant to be overridden by Process subclasses, the + /// subclasses should implement Process::DoWriteMemory (lldb::addr_t, + /// size_t, void *). /// /// @param[in] vm_addr /// A virtual load address that indicates where to start writing @@ -1972,9 +1944,9 @@ public: //------------------------------------------------------------------ /// Actually allocate memory in the process. /// - /// This function will allocate memory in the process's address - /// space. This can't rely on the generic function calling mechanism, - /// since that requires this function. + /// This function will allocate memory in the process's address space. This + /// can't rely on the generic function calling mechanism, since that + /// requires this function. /// /// @param[in] size /// The size of the allocation requested. @@ -1997,9 +1969,9 @@ public: //------------------------------------------------------------------ /// The public interface to allocating memory in the process. /// - /// This function will allocate memory in the process's address - /// space. This can't rely on the generic function calling mechanism, - /// since that requires this function. + /// This function will allocate memory in the process's address space. This + /// can't rely on the generic function calling mechanism, since that + /// requires this function. /// /// @param[in] size /// The size of the allocation requested. @@ -2023,9 +1995,9 @@ public: /// The public interface to allocating memory in the process, this also /// clears the allocated memory. /// - /// This function will allocate memory in the process's address - /// space. This can't rely on the generic function calling mechanism, - /// since that requires this function. + /// This function will allocate memory in the process's address space. This + /// can't rely on the generic function calling mechanism, since that + /// requires this function. /// /// @param[in] size /// The size of the allocation requested. @@ -2067,18 +2039,18 @@ public: /// Locate the memory region that contains load_addr. /// /// If load_addr is within the address space the process has mapped - /// range_info will be filled in with the start and end of that range - /// as well as the permissions for that range and range_info.GetMapped - /// will return true. + /// range_info will be filled in with the start and end of that range as + /// well as the permissions for that range and range_info.GetMapped will + /// return true. /// - /// If load_addr is outside any mapped region then range_info will - /// have its start address set to load_addr and the end of the - /// range will indicate the start of the next mapped range or be - /// set to LLDB_INVALID_ADDRESS if there are no valid mapped ranges - /// between load_addr and the end of the process address space. + /// If load_addr is outside any mapped region then range_info will have its + /// start address set to load_addr and the end of the range will indicate + /// the start of the next mapped range or be set to LLDB_INVALID_ADDRESS if + /// there are no valid mapped ranges between load_addr and the end of the + /// process address space. /// - /// GetMemoryRegionInfo will only return an error if it is - /// unimplemented for the current process. + /// GetMemoryRegionInfo will only return an error if it is unimplemented for + /// the current process. /// /// @param[in] load_addr /// The load address to query the range_info for. @@ -2131,9 +2103,9 @@ public: //------------------------------------------------------------------ /// Attempt to get the attributes for a region of memory in the process. /// - /// It may be possible for the remote debug server to inspect attributes - /// for a region of memory in the process, such as whether there is a - /// valid page of memory at a given address or whether that page is + /// It may be possible for the remote debug server to inspect attributes for + /// a region of memory in the process, such as whether there is a valid page + /// of memory at a given address or whether that page is /// readable/writable/executable by the process. /// /// @param[in] load_addr @@ -2153,8 +2125,8 @@ public: uint32_t &permissions); //------------------------------------------------------------------ - /// Determines whether executing JIT-compiled code in this process - /// is possible. + /// Determines whether executing JIT-compiled code in this process is + /// possible. /// /// @return /// True if execution of JIT code is possible; false otherwise. @@ -2162,8 +2134,7 @@ public: bool CanJIT(); //------------------------------------------------------------------ - /// Sets whether executing JIT-compiled code in this process - /// is possible. + /// Sets whether executing JIT-compiled code in this process is possible. /// /// @param[in] can_jit /// True if execution of JIT code is possible; false otherwise. @@ -2171,8 +2142,8 @@ public: void SetCanJIT(bool can_jit); //------------------------------------------------------------------ - /// Determines whether executing function calls using the interpreter - /// is possible for this process. + /// Determines whether executing function calls using the interpreter is + /// possible for this process. /// /// @return /// True if possible; false otherwise. @@ -2180,8 +2151,8 @@ public: bool CanInterpretFunctionCalls() { return m_can_interpret_function_calls; } //------------------------------------------------------------------ - /// Sets whether executing function calls using the interpreter - /// is possible for this process. + /// Sets whether executing function calls using the interpreter is possible + /// for this process. /// /// @param[in] can_interpret_function_calls /// True if possible; false otherwise. @@ -2191,8 +2162,8 @@ public: } //------------------------------------------------------------------ - /// Sets whether executing code in this process is possible. - /// This could be either through JIT or interpreting. + /// Sets whether executing code in this process is possible. This could be + /// either through JIT or interpreting. /// /// @param[in] can_run_code /// True if execution of code is possible; false otherwise. @@ -2202,8 +2173,8 @@ public: //------------------------------------------------------------------ /// Actually deallocate memory in the process. /// - /// This function will deallocate memory in the process's address - /// space that was allocated with AllocateMemory. + /// This function will deallocate memory in the process's address space that + /// was allocated with AllocateMemory. /// /// @param[in] ptr /// A return value from AllocateMemory, pointing to the memory you @@ -2223,8 +2194,8 @@ public: //------------------------------------------------------------------ /// The public interface to deallocating memory in the process. /// - /// This function will deallocate memory in the process's address - /// space that was allocated with AllocateMemory. + /// This function will deallocate memory in the process's address space that + /// was allocated with AllocateMemory. /// /// @param[in] ptr /// A return value from AllocateMemory, pointing to the memory you @@ -2238,20 +2209,19 @@ public: //------------------------------------------------------------------ /// Get any available STDOUT. /// - /// Calling this method is a valid operation only if all of the - /// following conditions are true: - /// 1) The process was launched, and not attached to. - /// 2) The process was not launched with eLaunchFlagDisableSTDIO. - /// 3) The process was launched without supplying a valid file path + /// Calling this method is a valid operation only if all of the following + /// conditions are true: 1) The process was launched, and not attached to. + /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The + /// process was launched without supplying a valid file path /// for STDOUT. /// - /// Note that the implementation will probably need to start a read - /// thread in the background to make sure that the pipe is drained - /// and the STDOUT buffered appropriately, to prevent the process - /// from deadlocking trying to write to a full buffer. + /// Note that the implementation will probably need to start a read thread + /// in the background to make sure that the pipe is drained and the STDOUT + /// buffered appropriately, to prevent the process from deadlocking trying + /// to write to a full buffer. /// - /// Events will be queued indicating that there is STDOUT available - /// that can be retrieved using this function. + /// Events will be queued indicating that there is STDOUT available that can + /// be retrieved using this function. /// /// @param[out] buf /// A buffer that will receive any STDOUT bytes that are @@ -2270,20 +2240,19 @@ public: //------------------------------------------------------------------ /// Get any available STDERR. /// - /// Calling this method is a valid operation only if all of the - /// following conditions are true: - /// 1) The process was launched, and not attached to. - /// 2) The process was not launched with eLaunchFlagDisableSTDIO. - /// 3) The process was launched without supplying a valid file path + /// Calling this method is a valid operation only if all of the following + /// conditions are true: 1) The process was launched, and not attached to. + /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The + /// process was launched without supplying a valid file path /// for STDERR. /// - /// Note that the implementation will probably need to start a read - /// thread in the background to make sure that the pipe is drained - /// and the STDERR buffered appropriately, to prevent the process - /// from deadlocking trying to write to a full buffer. + /// Note that the implementation will probably need to start a read thread + /// in the background to make sure that the pipe is drained and the STDERR + /// buffered appropriately, to prevent the process from deadlocking trying + /// to write to a full buffer. /// - /// Events will be queued indicating that there is STDERR available - /// that can be retrieved using this function. + /// Events will be queued indicating that there is STDERR available that can + /// be retrieved using this function. /// /// @param[in] buf /// A buffer that will receive any STDERR bytes that are @@ -2302,11 +2271,10 @@ public: //------------------------------------------------------------------ /// Puts data into this process's STDIN. /// - /// Calling this method is a valid operation only if all of the - /// following conditions are true: - /// 1) The process was launched, and not attached to. - /// 2) The process was not launched with eLaunchFlagDisableSTDIO. - /// 3) The process was launched without supplying a valid file path + /// Calling this method is a valid operation only if all of the following + /// conditions are true: 1) The process was launched, and not attached to. + /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The + /// process was launched without supplying a valid file path /// for STDIN. /// /// @param[in] buf @@ -2473,8 +2441,7 @@ public: /// Waits for the process state to be running within a given msec timeout. /// /// The main purpose of this is to implement an interlock waiting for - /// HandlePrivateEvent - /// to push an IOHandler. + /// HandlePrivateEvent to push an IOHandler. /// /// @param[in] timeout_msec /// The maximum time length to wait for the process to transition to the @@ -2488,8 +2455,8 @@ public: hijack_listener); // Pass an empty ListenerSP to use builtin listener //-------------------------------------------------------------------------------------- - /// Centralize the code that handles and prints descriptions for process state - /// changes. + /// Centralize the code that handles and prints descriptions for process + /// state changes. /// /// @param[in] event_sp /// The process state changed event @@ -2534,8 +2501,8 @@ public: /// event, then make a new listener, set to listen to process events, and /// then call this with that listener. Then you will have to wait on that /// listener explicitly for events (rather than using the GetNextEvent & - /// WaitFor* - /// calls above. Be sure to call RestoreProcessEvents when you are done. + /// WaitFor* calls above. Be sure to call RestoreProcessEvents when you are + /// done. /// /// @param[in] listener /// This is the new listener to whom all process events will be delivered. @@ -2662,10 +2629,10 @@ public: GetInstrumentationRuntime(lldb::InstrumentationRuntimeType type); //------------------------------------------------------------------ - /// Try to fetch the module specification for a module with the - /// given file name and architecture. Process sub-classes have to - /// override this method if they support platforms where the - /// Platform object can't get the module spec for all module. + /// Try to fetch the module specification for a module with the given file + /// name and architecture. Process sub-classes have to override this method + /// if they support platforms where the Platform object can't get the module + /// spec for all module. /// /// @param[in] module_file_spec /// The file name of the module to get specification for. @@ -2689,8 +2656,8 @@ public: //------------------------------------------------------------------ /// Try to find the load address of a file. - /// The load address is defined as the address of the first memory - /// region what contains data mapped from the specified file. + /// The load address is defined as the address of the first memory region + /// what contains data mapped from the specified file. /// /// @param[in] file /// The name of the file whose load address we are looking for @@ -2717,12 +2684,11 @@ public: //------------------------------------------------------------------ /// Find the next branch instruction to set a breakpoint on /// - /// When instruction stepping through a source line, instead of - /// stepping through each instruction, we can put a breakpoint on - /// the next branch instruction (within the range of instructions - /// we are stepping through) and continue the process to there, - /// yielding significant performance benefits over instruction - /// stepping. + /// When instruction stepping through a source line, instead of stepping + /// through each instruction, we can put a breakpoint on the next branch + /// instruction (within the range of instructions we are stepping through) + /// and continue the process to there, yielding significant performance + /// benefits over instruction stepping. /// /// @param[in] default_stop_addr /// The address of the instruction where lldb would put a @@ -2749,8 +2715,8 @@ public: /// The default implementation here will always return an error indiciating /// the feature is unsupported. /// - /// StructuredDataPlugin implementations will call this to configure - /// a feature that has been reported as being supported. + /// StructuredDataPlugin implementations will call this to configure a + /// feature that has been reported as being supported. /// /// @param[in] type_name /// The StructuredData type name as previously discovered by @@ -2772,13 +2738,12 @@ public: const StructuredData::ObjectSP &config_sp); //------------------------------------------------------------------ - /// Broadcasts the given structured data object from the given - /// plugin. + /// Broadcasts the given structured data object from the given plugin. /// - /// StructuredDataPlugin instances can use this to optionally - /// broadcast any of their data if they want to make it available - /// for clients. The data will come in on the structured data - /// event bit (eBroadcastBitStructuredData). + /// StructuredDataPlugin instances can use this to optionally broadcast any + /// of their data if they want to make it available for clients. The data + /// will come in on the structured data event bit + /// (eBroadcastBitStructuredData). /// /// @param[in] object_sp /// The structured data object to broadcast. @@ -2791,12 +2756,12 @@ public: const lldb::StructuredDataPluginSP &plugin_sp); //------------------------------------------------------------------ - /// Returns the StructuredDataPlugin associated with a given type - /// name, if there is one. + /// Returns the StructuredDataPlugin associated with a given type name, if + /// there is one. /// /// There will only be a plugin for a given StructuredDataType if the - /// debugged process monitor claims that the feature is supported. - /// This is one way to tell whether a feature is available. + /// debugged process monitor claims that the feature is supported. This is + /// one way to tell whether a feature is available. /// /// @return /// The plugin if one is available for the specified feature; @@ -2806,17 +2771,14 @@ public: GetStructuredDataPlugin(const ConstString &type_name) const; //------------------------------------------------------------------ - /// Starts tracing with the configuration provided in options. To - /// enable tracing on the complete process the thread_id in the - /// options should be set to LLDB_INVALID_THREAD_ID. The API returns - /// a user_id which is needed by other API's that manipulate the - /// trace instance. - /// The handling of erroneous or unsupported configuration is left - /// to the trace technology implementations in the server, as they - /// could be returned as an error, or rounded to a valid - /// configuration to start tracing. In the later case the - /// GetTraceConfig should supply the actual used trace - /// configuration. + /// Starts tracing with the configuration provided in options. To enable + /// tracing on the complete process the thread_id in the options should be + /// set to LLDB_INVALID_THREAD_ID. The API returns a user_id which is needed + /// by other API's that manipulate the trace instance. The handling of + /// erroneous or unsupported configuration is left to the trace technology + /// implementations in the server, as they could be returned as an error, or + /// rounded to a valid configuration to start tracing. In the later case the + /// GetTraceConfig should supply the actual used trace configuration. //------------------------------------------------------------------ virtual lldb::user_id_t StartTrace(const TraceOptions &options, Status &error) { @@ -2825,25 +2787,23 @@ public: } //------------------------------------------------------------------ - /// Stops the tracing instance leading to deletion of the trace - /// data. The tracing instance is identified by the user_id which - /// is obtained when tracing was started from the StartTrace. - /// In case tracing of the complete process needs to be stopped - /// the thread_id should be set to LLDB_INVALID_THREAD_ID. - /// In the other case that tracing on an individual thread needs - /// to be stopped a thread_id can be supplied. + /// Stops the tracing instance leading to deletion of the trace data. The + /// tracing instance is identified by the user_id which is obtained when + /// tracing was started from the StartTrace. In case tracing of the complete + /// process needs to be stopped the thread_id should be set to + /// LLDB_INVALID_THREAD_ID. In the other case that tracing on an individual + /// thread needs to be stopped a thread_id can be supplied. //------------------------------------------------------------------ virtual Status StopTrace(lldb::user_id_t uid, lldb::tid_t thread_id) { return Status("Not implemented"); } //------------------------------------------------------------------ - /// Provides the trace data as raw bytes. A buffer needs to be - /// supplied to copy the trace data. The exact behavior of this API - /// may vary across trace technology, as some may support partial - /// reading of the trace data from a specified offset while some - /// may not. The thread_id should be used to select a particular - /// thread for trace extraction. + /// Provides the trace data as raw bytes. A buffer needs to be supplied to + /// copy the trace data. The exact behavior of this API may vary across + /// trace technology, as some may support partial reading of the trace data + /// from a specified offset while some may not. The thread_id should be used + /// to select a particular thread for trace extraction. //------------------------------------------------------------------ virtual Status GetData(lldb::user_id_t uid, lldb::tid_t thread_id, llvm::MutableArrayRef<uint8_t> &buffer, @@ -2862,12 +2822,12 @@ public: //------------------------------------------------------------------ /// API to obtain the trace configuration used by a trace instance. - /// Configurations that may be specific to some trace technology - /// should be stored in the custom parameters. The options are - /// transported to the server, which shall interpret accordingly. - /// The thread_id can be specified in the options to obtain the - /// configuration used by a specific thread. The thread_id specified - /// should also match the uid otherwise an error will be returned. + /// Configurations that may be specific to some trace technology should be + /// stored in the custom parameters. The options are transported to the + /// server, which shall interpret accordingly. The thread_id can be + /// specified in the options to obtain the configuration used by a specific + /// thread. The thread_id specified should also match the uid otherwise an + /// error will be returned. //------------------------------------------------------------------ virtual Status GetTraceConfig(lldb::user_id_t uid, TraceOptions &options) { return Status("Not implemented"); @@ -2879,8 +2839,8 @@ protected: lldb::StateType GetPrivateState(); //------------------------------------------------------------------ - /// The "private" side of resuming a process. This doesn't alter the - /// state of m_run_lock, but just causes the process to resume. + /// The "private" side of resuming a process. This doesn't alter the state + /// of m_run_lock, but just causes the process to resume. /// /// @return /// An Status object describing the success or failure of the resume. @@ -2897,16 +2857,16 @@ protected: /// /// A facility for printing a warning to the user once per repeat_key. /// - /// warning_type is from the Process::Warnings enums. - /// repeat_key is a pointer value that will be used to ensure that the - /// warning message is not printed multiple times. For instance, with a - /// warning about a function being optimized, you can pass the CompileUnit - /// pointer to have the warning issued for only the first function in a - /// CU, or the Function pointer to have it issued once for every function, - /// or a Module pointer to have it issued once per Module. + /// warning_type is from the Process::Warnings enums. repeat_key is a + /// pointer value that will be used to ensure that the warning message is + /// not printed multiple times. For instance, with a warning about a + /// function being optimized, you can pass the CompileUnit pointer to have + /// the warning issued for only the first function in a CU, or the Function + /// pointer to have it issued once for every function, or a Module pointer + /// to have it issued once per Module. /// - /// Classes outside Process should call a specific PrintWarning method - /// so that the warning strings are all centralized in Process, instead of + /// Classes outside Process should call a specific PrintWarning method so + /// that the warning strings are all centralized in Process, instead of /// calling PrintWarning() directly. /// /// @param [in] warning_type @@ -2987,18 +2947,17 @@ protected: void ForceNextEventDelivery() { m_force_next_event_delivery = true; } //------------------------------------------------------------------ - /// Loads any plugins associated with asynchronous structured data - /// and maps the relevant supported type name to the plugin. + /// Loads any plugins associated with asynchronous structured data and maps + /// the relevant supported type name to the plugin. /// - /// Processes can receive asynchronous structured data from the - /// process monitor. This method will load and map any structured - /// data plugins that support the given set of supported type names. - /// Later, if any of these features are enabled, the process monitor - /// is free to generate asynchronous structured data. The data must - /// come in as a single \b StructuredData::Dictionary. That dictionary - /// must have a string field named 'type', with a value that equals - /// the relevant type name string (one of the values in - /// \b supported_type_names). + /// Processes can receive asynchronous structured data from the process + /// monitor. This method will load and map any structured data plugins that + /// support the given set of supported type names. Later, if any of these + /// features are enabled, the process monitor is free to generate + /// asynchronous structured data. The data must come in as a single \b + /// StructuredData::Dictionary. That dictionary must have a string field + /// named 'type', with a value that equals the relevant type name string + /// (one of the values in \b supported_type_names). /// /// @param[in] supported_type_names /// An array of zero or more type names. Each must be unique. @@ -3011,10 +2970,9 @@ protected: //------------------------------------------------------------------ /// Route the incoming structured data dictionary to the right plugin. /// - /// The incoming structured data must be a dictionary, and it must - /// have a key named 'type' that stores a string value. The string - /// value must be the name of the structured data feature that - /// knows how to handle it. + /// The incoming structured data must be a dictionary, and it must have a + /// key named 'type' that stores a string value. The string value must be + /// the name of the structured data feature that knows how to handle it. /// /// @param[in] object_sp /// When non-null and pointing to a dictionary, the 'type' @@ -3256,14 +3214,12 @@ protected: private: //------------------------------------------------------------------ - /// This is the part of the event handling that for a process event. - /// It decides what to do with the event and returns true if the - /// event needs to be propagated to the user, and false otherwise. - /// If the event is not propagated, this call will most likely set - /// the target to executing again. - /// There is only one place where this call should be called, - /// HandlePrivateEvent. - /// Don't call it from anywhere else... + /// This is the part of the event handling that for a process event. It + /// decides what to do with the event and returns true if the event needs to + /// be propagated to the user, and false otherwise. If the event is not + /// propagated, this call will most likely set the target to executing + /// again. There is only one place where this call should be called, + /// HandlePrivateEvent. Don't call it from anywhere else... /// /// @param[in] event_ptr /// This is the event we are handling. diff --git a/lldb/include/lldb/Target/StackFrame.h b/lldb/include/lldb/Target/StackFrame.h index 60b53c852b6..ce9b1622767 100644 --- a/lldb/include/lldb/Target/StackFrame.h +++ b/lldb/include/lldb/Target/StackFrame.h @@ -32,7 +32,7 @@ namespace lldb_private { /// @class StackFrame StackFrame.h "lldb/Target/StackFrame.h" /// -/// @brief This base class provides an interface to stack frames. +/// This base class provides an interface to stack frames. /// /// StackFrames may have a Canonical Frame Address (CFA) or not. /// A frame may have a plain pc value or it may have a pc value + stop_id @@ -59,10 +59,10 @@ public: /// /// This is the one constructor that doesn't take a RegisterContext /// parameter. This ctor may be called when creating a history StackFrame; - /// these are used if we've collected a stack trace of pc addresses at - /// some point in the past. We may only have pc values. We may have pc - /// values and the stop_id when the stack trace was recorded. We may have a - /// CFA, or more likely, we won't. + /// these are used if we've collected a stack trace of pc addresses at some + /// point in the past. We may only have pc values. We may have pc values + /// and the stop_id when the stack trace was recorded. We may have a CFA, + /// or more likely, we won't. /// /// @param [in] thread_sp /// The Thread that this frame belongs to. @@ -165,9 +165,9 @@ public: /// Provide a SymbolContext for this StackFrame's current pc value. /// /// The StackFrame maintains this SymbolContext and adds additional - /// information - /// to it on an as-needed basis. This helps to avoid different functions - /// looking up symbolic information for a given pc value multiple times. + /// information to it on an as-needed basis. This helps to avoid different + /// functions looking up symbolic information for a given pc value multiple + /// times. /// /// @params [in] resolve_scope /// Flags from the SymbolContextItem enumerated type which specify what @@ -182,9 +182,9 @@ public: //------------------------------------------------------------------ /// Return the Canonical Frame Address (DWARF term) for this frame. /// - /// The CFA is typically the value of the stack pointer register before - /// the call invocation is made. It will not change during the lifetime - /// of a stack frame. It is often not the same thing as the frame pointer + /// The CFA is typically the value of the stack pointer register before the + /// call invocation is made. It will not change during the lifetime of a + /// stack frame. It is often not the same thing as the frame pointer /// register value. /// /// Live StackFrames will always have a CFA but other types of frames may @@ -220,9 +220,8 @@ public: //------------------------------------------------------------------ /// Get the current lexical scope block for this StackFrame, if possible. /// - /// If debug information is available for this stack frame, return a - /// pointer to the innermost lexical Block that the frame is currently - /// executing. + /// If debug information is available for this stack frame, return a pointer + /// to the innermost lexical Block that the frame is currently executing. /// /// @return /// A pointer to the current Block. nullptr is returned if this can @@ -251,11 +250,12 @@ public: } //------------------------------------------------------------------ - /// Retrieve the list of variables that are in scope at this StackFrame's pc. + /// Retrieve the list of variables that are in scope at this StackFrame's + /// pc. /// /// A frame that is not live may return an empty VariableList for a given - /// pc value even though variables would be available at this point if - /// it were a live stack frame. + /// pc value even though variables would be available at this point if it + /// were a live stack frame. /// /// @param[in] get_file_globals /// Whether to also retrieve compilation-unit scoped variables @@ -268,11 +268,12 @@ public: VariableList *GetVariableList(bool get_file_globals); //------------------------------------------------------------------ - /// Retrieve the list of variables that are in scope at this StackFrame's pc. + /// Retrieve the list of variables that are in scope at this StackFrame's + /// pc. /// /// A frame that is not live may return an empty VariableListSP for a - /// given pc value even though variables would be available at this point - /// if it were a live stack frame. + /// given pc value even though variables would be available at this point if + /// it were a live stack frame. /// /// @param[in] get_file_globals /// Whether to also retrieve compilation-unit scoped variables @@ -287,8 +288,8 @@ public: bool must_have_valid_location = false); //------------------------------------------------------------------ - /// Create a ValueObject for a variable name / pathname, possibly - /// including simple dereference/child selection syntax. + /// Create a ValueObject for a variable name / pathname, possibly including + /// simple dereference/child selection syntax. /// /// @param[in] var_expr /// The string specifying a variable to base the VariableObject off @@ -327,8 +328,8 @@ public: bool HasDebugInformation(); //------------------------------------------------------------------ - /// Return the disassembly for the instructions of this StackFrame's function - /// as a single C string. + /// Return the disassembly for the instructions of this StackFrame's + /// function as a single C string. /// /// @return // C string with the assembly instructions for this function. @@ -366,8 +367,8 @@ public: void Dump(Stream *strm, bool show_frame_index, bool show_fullpaths); //------------------------------------------------------------------ - /// Print a description of this stack frame and/or the source context/assembly - /// for this stack frame. + /// Print a description of this stack frame and/or the source + /// context/assembly for this stack frame. /// /// @param[in] strm /// The Stream to send the output to. @@ -392,9 +393,9 @@ public: bool show_unique = false, const char *frame_marker = nullptr); //------------------------------------------------------------------ - /// Query whether this frame is a concrete frame on the call stack, - /// or if it is an inlined frame derived from the debug information - /// and presented by the debugger. + /// Query whether this frame is a concrete frame on the call stack, or if it + /// is an inlined frame derived from the debug information and presented by + /// the debugger. /// /// @return /// true if this is an inlined frame. @@ -402,7 +403,8 @@ public: bool IsInlined(); //------------------------------------------------------------------ - /// Query this frame to find what frame it is in this Thread's StackFrameList. + /// Query this frame to find what frame it is in this Thread's + /// StackFrameList. /// /// @return /// StackFrame index 0 indicates the currently-executing function. Inline @@ -411,8 +413,8 @@ public: uint32_t GetFrameIndex() const; //------------------------------------------------------------------ - /// Query this frame to find what frame it is in this Thread's StackFrameList, - /// not counting inlined frames. + /// Query this frame to find what frame it is in this Thread's + /// StackFrameList, not counting inlined frames. /// /// @return /// StackFrame index 0 indicates the currently-executing function. Inline @@ -442,8 +444,7 @@ public: //------------------------------------------------------------------ /// Add an arbitrary Variable object (e.g. one that specifics a global or - /// static) - /// to a StackFrame's list of ValueObjects. + /// static) to a StackFrame's list of ValueObjects. /// /// @params [in] variable_sp /// The Variable to base this ValueObject on @@ -460,8 +461,8 @@ public: lldb::DynamicValueType use_dynamic); //------------------------------------------------------------------ - /// Query this frame to determine what the default language should be - /// when parsing expressions given the execution context. + /// Query this frame to determine what the default language should be when + /// parsing expressions given the execution context. /// /// @return /// The language of the frame if known, else lldb::eLanguageTypeUnknown. @@ -487,8 +488,8 @@ public: //------------------------------------------------------------------ /// Attempt to reconstruct the ValueObject for the address contained in a - /// given register plus an offset. The ExpressionPath should indicate how to - /// get to this value using "frame variable." + /// given register plus an offset. The ExpressionPath should indicate how + /// to get to this value using "frame variable." /// /// @params [in] reg /// The name of the register. diff --git a/lldb/include/lldb/Target/SystemRuntime.h b/lldb/include/lldb/Target/SystemRuntime.h index 8c6c2ece967..06cc3ec2d01 100644 --- a/lldb/include/lldb/Target/SystemRuntime.h +++ b/lldb/include/lldb/Target/SystemRuntime.h @@ -29,20 +29,20 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class SystemRuntime SystemRuntime.h "lldb/Target/SystemRuntime.h" -/// @brief A plug-in interface definition class for system runtimes. +/// A plug-in interface definition class for system runtimes. /// /// The system runtime plugins can collect information from the system -/// libraries during a Process' lifetime and provide information about -/// how objects/threads were originated. +/// libraries during a Process' lifetime and provide information about how +/// objects/threads were originated. /// -/// For instance, a system runtime plugin use a breakpoint when threads -/// are created to record the backtrace of where that thread was created. -/// Later, when backtracing the created thread, it could extend the backtrace -/// to show where it was originally created from. +/// For instance, a system runtime plugin use a breakpoint when threads are +/// created to record the backtrace of where that thread was created. Later, +/// when backtracing the created thread, it could extend the backtrace to show +/// where it was originally created from. /// -/// The plugin will insert its own breakpoint when Created and start collecting -/// information. Later when it comes time to augment a Thread, it can be -/// asked to provide that information. +/// The plugin will insert its own breakpoint when Created and start +/// collecting information. Later when it comes time to augment a Thread, it +/// can be asked to provide that information. /// //---------------------------------------------------------------------- @@ -51,9 +51,8 @@ public: //------------------------------------------------------------------ /// Find a system runtime plugin for a given process. /// - /// Scans the installed SystemRuntime plugins and tries to find - /// an instance that can be used to track image changes in \a - /// process. + /// Scans the installed SystemRuntime plugins and tries to find an instance + /// that can be used to track image changes in \a process. /// /// @param[in] process /// The process for which to try and locate a system runtime @@ -69,60 +68,60 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// The destructor is virtual since this class is designed to be - /// inherited by the plug-in instance. + /// The destructor is virtual since this class is designed to be inherited + /// by the plug-in instance. //------------------------------------------------------------------ ~SystemRuntime() override; //------------------------------------------------------------------ /// Called after attaching to a process. /// - /// Allow the SystemRuntime plugin to execute some code after attaching - /// to a process. + /// Allow the SystemRuntime plugin to execute some code after attaching to a + /// process. //------------------------------------------------------------------ virtual void DidAttach(); //------------------------------------------------------------------ /// Called after launching a process. /// - /// Allow the SystemRuntime plugin to execute some code after launching - /// a process. + /// Allow the SystemRuntime plugin to execute some code after launching a + /// process. //------------------------------------------------------------------ virtual void DidLaunch(); //------------------------------------------------------------------ /// Called when modules have been loaded in the process. /// - /// Allow the SystemRuntime plugin to enable logging features in the - /// system runtime libraries. + /// Allow the SystemRuntime plugin to enable logging features in the system + /// runtime libraries. //------------------------------------------------------------------ virtual void ModulesDidLoad(lldb_private::ModuleList &module_list); //------------------------------------------------------------------ /// Called before detaching from a process. /// - /// This will give a SystemRuntime plugin a chance to free any resources - /// in the inferior process before we detach. + /// This will give a SystemRuntime plugin a chance to free any resources in + /// the inferior process before we detach. //------------------------------------------------------------------ virtual void Detach(); //------------------------------------------------------------------ - /// Return a list of thread origin extended backtraces that may - /// be available. + /// Return a list of thread origin extended backtraces that may be + /// available. /// /// A System Runtime may be able to provide a backtrace of when this - /// thread was originally created. Furthermore, it may be able to - /// provide that extended backtrace for different styles of creation. - /// On a system with both pthreads and libdispatch, aka Grand Central - /// Dispatch, queues, the system runtime may be able to provide the - /// pthread creation of the thread and it may also be able to provide - /// the backtrace of when this GCD queue work block was enqueued. - /// The caller may request these different origins by name. - /// - /// The names will be provided in the order that they are most likely - /// to be requested. For instance, a most natural order may be to - /// request the GCD libdispatch queue origin. If there is none, then - /// request the pthread origin. + /// thread was originally created. Furthermore, it may be able to provide + /// that extended backtrace for different styles of creation. On a system + /// with both pthreads and libdispatch, aka Grand Central Dispatch, queues, + /// the system runtime may be able to provide the pthread creation of the + /// thread and it may also be able to provide the backtrace of when this GCD + /// queue work block was enqueued. The caller may request these different + /// origins by name. + /// + /// The names will be provided in the order that they are most likely to be + /// requested. For instance, a most natural order may be to request the GCD + /// libdispatch queue origin. If there is none, then request the pthread + /// origin. /// /// @return /// A vector of ConstStrings with names like "pthread" or "libdispatch". @@ -135,13 +134,12 @@ public: /// Return a Thread which shows the origin of this thread's creation. /// /// This likely returns a HistoryThread which shows how thread was - /// originally created (e.g. "pthread" type), or how the work that - /// is currently executing on it was originally enqueued (e.g. - /// "libdispatch" type). + /// originally created (e.g. "pthread" type), or how the work that is + /// currently executing on it was originally enqueued (e.g. "libdispatch" + /// type). /// - /// There may be a chain of thread-origins; it may be informative to - /// the end user to query the returned ThreadSP for its origins as - /// well. + /// There may be a chain of thread-origins; it may be informative to the end + /// user to query the returned ThreadSP for its origins as well. /// /// @param [in] thread /// The thread to examine. @@ -168,8 +166,8 @@ public: /// a libdispatch queue in the future, or it represents a function/block /// that is currently executing on a thread. /// - /// This method will report a thread backtrace of the function that - /// enqueued it originally, if possible. + /// This method will report a thread backtrace of the function that enqueued + /// it originally, if possible. /// /// @param [in] queue_item_sp /// The QueueItem that we are getting an extended backtrace for. @@ -189,10 +187,11 @@ public: } //------------------------------------------------------------------ - /// Populate the Process' QueueList with libdispatch / GCD queues that exist. + /// Populate the Process' QueueList with libdispatch / GCD queues that + /// exist. /// - /// When process execution is paused, the SystemRuntime may be called to fill - /// in the list of Queues that currently exist. + /// When process execution is paused, the SystemRuntime may be called to + /// fill in the list of Queues that currently exist. /// /// @param [out] queue_list /// This QueueList will be cleared, and any queues that currently exist @@ -205,12 +204,10 @@ public: /// Get the queue name for a thread given a thread's dispatch_qaddr. /// /// On systems using libdispatch queues, a thread may be associated with a - /// queue. - /// There will be a call to get the thread's dispatch_qaddr. At the - /// dispatch_qaddr - /// we will find the address of this thread's dispatch_queue_t structure. - /// Given the address of the dispatch_queue_t structure for a thread, - /// get the queue name and return it. + /// queue. There will be a call to get the thread's dispatch_qaddr. At the + /// dispatch_qaddr we will find the address of this thread's + /// dispatch_queue_t structure. Given the address of the dispatch_queue_t + /// structure for a thread, get the queue name and return it. /// /// @param [in] dispatch_qaddr /// The address of the dispatch_qaddr pointer for this thread. @@ -229,12 +226,10 @@ public: /// dispatch_qaddr. /// /// On systems using libdispatch queues, a thread may be associated with a - /// queue. - /// There will be a call to get the thread's dispatch_qaddr. At the - /// dispatch_qaddr - /// we will find the address of this thread's dispatch_queue_t structure. - /// Given the address of the dispatch_queue_t structure for a thread, - /// get the queue ID and return it. + /// queue. There will be a call to get the thread's dispatch_qaddr. At the + /// dispatch_qaddr we will find the address of this thread's + /// dispatch_queue_t structure. Given the address of the dispatch_queue_t + /// structure for a thread, get the queue ID and return it. /// /// @param [in] dispatch_qaddr /// The address of the dispatch_qaddr pointer for this thread. @@ -252,10 +247,8 @@ public: /// dispatch_qaddr. /// /// On systems using libdispatch queues, a thread may be associated with a - /// queue. - /// There will be a call to get the thread's dispatch_qaddr. - /// Given the thread's dispatch_qaddr, find the libdispatch_queue_t address - /// and + /// queue. There will be a call to get the thread's dispatch_qaddr. Given + /// the thread's dispatch_qaddr, find the libdispatch_queue_t address and /// return it. /// /// @param [in] dispatch_qaddr @@ -274,8 +267,8 @@ public: /// Retrieve the Queue kind for the queue at a thread's dispatch_qaddr. /// /// Retrieve the Queue kind - either eQueueKindSerial or - /// eQueueKindConcurrent, indicating that this queue processes work - /// items serially or concurrently. + /// eQueueKindConcurrent, indicating that this queue processes work items + /// serially or concurrently. /// /// @return /// The Queue kind, if it could be read, else eQueueKindUnknown. @@ -288,8 +281,8 @@ public: /// Get the pending work items for a libdispatch Queue /// /// If this system/process is using libdispatch and the runtime can do so, - /// retrieve the list of pending work items for the specified Queue and - /// add it to the Queue. + /// retrieve the list of pending work items for the specified Queue and add + /// it to the Queue. /// /// @param [in] queue /// The queue of interest. @@ -300,8 +293,8 @@ public: /// Complete the fields in a QueueItem /// /// PopulatePendingItemsForQueue() may not fill in all of the QueueItem - /// details; when the remaining fields are needed, they will be - /// fetched by call this method. + /// details; when the remaining fields are needed, they will be fetched by + /// call this method. /// /// @param [in] queue_item /// The QueueItem that we will be completing. @@ -316,8 +309,7 @@ public: //------------------------------------------------------------------ /// Add key-value pairs to the StructuredData dictionary object with /// information debugserver may need when constructing the - /// jThreadExtendedInfo - /// packet. + /// jThreadExtendedInfo packet. /// /// @param [out] dict /// Dictionary to which key-value pairs should be added; they will diff --git a/lldb/include/lldb/Utility/ArchSpec.h b/lldb/include/lldb/Utility/ArchSpec.h index 7654af26ca2..931b3334673 100644 --- a/lldb/include/lldb/Utility/ArchSpec.h +++ b/lldb/include/lldb/Utility/ArchSpec.h @@ -23,13 +23,13 @@ namespace lldb_private { //---------------------------------------------------------------------- -/// @class ArchSpec ArchSpec.h "lldb/Utility/ArchSpec.h" -/// @brief An architecture specification class. +/// @class ArchSpec ArchSpec.h "lldb/Utility/ArchSpec.h" An architecture +/// specification class. /// /// A class designed to be created from a cpu type and subtype, a -/// string representation, or an llvm::Triple. Keeping all of the -/// conversions of strings to architecture enumeration values confined -/// to this class allows new architecture support to be added easily. +/// string representation, or an llvm::Triple. Keeping all of the conversions +/// of strings to architecture enumeration values confined to this class +/// allows new architecture support to be added easily. //---------------------------------------------------------------------- class ArchSpec { public: @@ -245,16 +245,15 @@ public: //------------------------------------------------------------------ /// Default constructor. /// - /// Default constructor that initializes the object with invalid - /// cpu type and subtype values. + /// Default constructor that initializes the object with invalid cpu type + /// and subtype values. //------------------------------------------------------------------ ArchSpec(); //------------------------------------------------------------------ /// Constructor over triple. /// - /// Constructs an ArchSpec with properties consistent with the given - /// Triple. + /// Constructs an ArchSpec with properties consistent with the given Triple. //------------------------------------------------------------------ explicit ArchSpec(const llvm::Triple &triple); explicit ArchSpec(const char *triple_cstr); @@ -262,8 +261,8 @@ public: //------------------------------------------------------------------ /// Constructor over architecture name. /// - /// Constructs an ArchSpec with properties consistent with the given - /// object type and architecture name. + /// Constructs an ArchSpec with properties consistent with the given object + /// type and architecture name. //------------------------------------------------------------------ explicit ArchSpec(ArchitectureType arch_type, uint32_t cpu_type, uint32_t cpu_subtype); @@ -284,7 +283,8 @@ public: //--------------------------------------------------------------------------- /// Returns true if the OS, vendor and environment fields of the triple are - /// unset. The triple is expected to be normalized (llvm::Triple::normalize). + /// unset. The triple is expected to be normalized + /// (llvm::Triple::normalize). //--------------------------------------------------------------------------- static bool ContainsOnlyArch(const llvm::Triple &normalized_triple); @@ -306,8 +306,8 @@ public: bool IsMIPS() const; //------------------------------------------------------------------ - /// Returns a string representing current architecture as a target CPU - /// for tools like compiler, disassembler etc. + /// Returns a string representing current architecture as a target CPU for + /// tools like compiler, disassembler etc. /// /// @return A string representing target CPU for the current /// architecture. @@ -329,8 +329,7 @@ public: void Clear(); //------------------------------------------------------------------ - /// Returns the size in bytes of an address of the current - /// architecture. + /// Returns the size in bytes of an address of the current architecture. /// /// @return The byte size of an address of the current architecture. //------------------------------------------------------------------ @@ -356,9 +355,8 @@ public: //------------------------------------------------------------------ /// Set the distribution id of the architecture. /// - /// This will be something like "ubuntu", "fedora", etc. on Linux. - /// This should be the same value returned by - /// HostInfo::GetDistributionId (). + /// This will be something like "ubuntu", "fedora", etc. on Linux. This + /// should be the same value returned by HostInfo::GetDistributionId (). ///------------------------------------------------------------------ void SetDistributionId(const char *distribution_id); @@ -395,13 +393,12 @@ public: //------------------------------------------------------------------ /// Merges fields from another ArchSpec into this ArchSpec. /// - /// This will use the supplied ArchSpec to fill in any fields of - /// the triple in this ArchSpec which were unspecified. This can - /// be used to refine a generic ArchSpec with a more specific one. - /// For example, if this ArchSpec's triple is something like - /// i386-unknown-unknown-unknown, and we have a triple which is - /// x64-pc-windows-msvc, then merging that triple into this one - /// will result in the triple i386-pc-windows-msvc. + /// This will use the supplied ArchSpec to fill in any fields of the triple + /// in this ArchSpec which were unspecified. This can be used to refine a + /// generic ArchSpec with a more specific one. For example, if this + /// ArchSpec's triple is something like i386-unknown-unknown-unknown, and we + /// have a triple which is x64-pc-windows-msvc, then merging that triple + /// into this one will result in the triple i386-pc-windows-msvc. /// //------------------------------------------------------------------ void MergeFrom(const ArchSpec &other); @@ -421,16 +418,16 @@ public: /// /// @return True if the object, and CPU were successfully set. /// - /// As a side effect, the vendor value is usually set to unknown. - /// The exections are + /// As a side effect, the vendor value is usually set to unknown. The + /// exections are /// aarch64-apple-ios /// arm-apple-ios /// thumb-apple-ios /// x86-apple- /// x86_64-apple- /// - /// As a side effect, the os value is usually set to unknown - /// The exceptions are + /// As a side effect, the os value is usually set to unknown The exceptions + /// are /// *-*-aix /// aarch64-apple-ios /// arm-apple-ios @@ -456,10 +453,10 @@ public: //------------------------------------------------------------------ /// Sets this ArchSpec's byte order. /// - /// In the common case there is no need to call this method as the - /// byte order can almost always be determined by the architecture. - /// However, many CPU's are bi-endian (ARM, Alpha, PowerPC, etc) - /// and the default/assumed byte order may be incorrect. + /// In the common case there is no need to call this method as the byte + /// order can almost always be determined by the architecture. However, many + /// CPU's are bi-endian (ARM, Alpha, PowerPC, etc) and the default/assumed + /// byte order may be incorrect. //------------------------------------------------------------------ void SetByteOrder(lldb::ByteOrder byte_order) { m_byte_order = byte_order; } @@ -476,16 +473,16 @@ public: //------------------------------------------------------------------ /// Architecture data byte width accessor /// - /// @return the size in 8-bit (host) bytes of a minimum addressable - /// unit from the Architecture's data bus + /// @return the size in 8-bit (host) bytes of a minimum addressable unit + /// from the Architecture's data bus //------------------------------------------------------------------ uint32_t GetDataByteSize() const; //------------------------------------------------------------------ /// Architecture code byte width accessor /// - /// @return the size in 8-bit (host) bytes of a minimum addressable - /// unit from the Architecture's code bus + /// @return the size in 8-bit (host) bytes of a minimum addressable unit + /// from the Architecture's code bus //------------------------------------------------------------------ uint32_t GetCodeByteSize() const; @@ -508,12 +505,12 @@ public: //------------------------------------------------------------------ /// Architecture tripple setter. /// - /// Configures this ArchSpec according to the given triple. If the - /// triple has unknown components in all of the vendor, OS, and - /// the optional environment field (i.e. "i386-unknown-unknown") - /// then default values are taken from the host. Architecture and - /// environment components are used to further resolve the CPU type - /// and subtype, endian characteristics, etc. + /// Configures this ArchSpec according to the given triple. If the triple + /// has unknown components in all of the vendor, OS, and the optional + /// environment field (i.e. "i386-unknown-unknown") then default values are + /// taken from the host. Architecture and environment components are used + /// to further resolve the CPU type and subtype, endian characteristics, + /// etc. /// /// @return A triple describing this ArchSpec. //------------------------------------------------------------------ @@ -530,8 +527,8 @@ public: lldb::ByteOrder GetDefaultEndian() const; //------------------------------------------------------------------ - /// Returns true if 'char' is a signed type by defualt in the - /// architecture false otherwise + /// Returns true if 'char' is a signed type by defualt in the architecture + /// false otherwise /// /// @return True if 'char' is a signed type by default on the /// architecture and false otherwise. @@ -539,18 +536,18 @@ public: bool CharIsSignedByDefault() const; //------------------------------------------------------------------ - /// Compare an ArchSpec to another ArchSpec, requiring an exact cpu - /// type match between them. - /// e.g. armv7s is not an exact match with armv7 - this would return false + /// Compare an ArchSpec to another ArchSpec, requiring an exact cpu type + /// match between them. e.g. armv7s is not an exact match with armv7 - this + /// would return false /// /// @return true if the two ArchSpecs match. //------------------------------------------------------------------ bool IsExactMatch(const ArchSpec &rhs) const; //------------------------------------------------------------------ - /// Compare an ArchSpec to another ArchSpec, requiring a compatible - /// cpu type match between them. - /// e.g. armv7s is compatible with armv7 - this method would return true + /// Compare an ArchSpec to another ArchSpec, requiring a compatible cpu type + /// match between them. e.g. armv7s is compatible with armv7 - this method + /// would return true /// /// @return true if the two ArchSpecs are compatible //------------------------------------------------------------------ @@ -566,12 +563,12 @@ public: //------------------------------------------------------------------ /// Detect whether this architecture uses thumb code exclusively /// - /// Some embedded ARM chips (e.g. the ARM Cortex M0-7 line) can - /// only execute the Thumb instructions, never Arm. We should normally - /// pick up arm/thumbness from their the processor status bits (cpsr/xpsr) - /// or hints on each function - but when doing bare-boards low level - /// debugging (especially common with these embedded processors), we may - /// not have those things easily accessible. + /// Some embedded ARM chips (e.g. the ARM Cortex M0-7 line) can only execute + /// the Thumb instructions, never Arm. We should normally pick up + /// arm/thumbness from their the processor status bits (cpsr/xpsr) or hints + /// on each function - but when doing bare-boards low level debugging + /// (especially common with these embedded processors), we may not have + /// those things easily accessible. /// /// @return true if this is an arm ArchSpec which can only execute Thumb /// instructions @@ -604,14 +601,13 @@ protected: }; //------------------------------------------------------------------ -/// @fn bool operator< (const ArchSpec& lhs, const ArchSpec& rhs) -/// @brief Less than operator. +/// @fn bool operator< (const ArchSpec& lhs, const ArchSpec& rhs) Less than +/// operator. /// -/// Tests two ArchSpec objects to see if \a lhs is less than \a -/// rhs. +/// Tests two ArchSpec objects to see if \a lhs is less than \a rhs. /// -/// @param[in] lhs The Left Hand Side ArchSpec object to compare. -/// @param[in] rhs The Left Hand Side ArchSpec object to compare. +/// @param[in] lhs The Left Hand Side ArchSpec object to compare. @param[in] +/// rhs The Left Hand Side ArchSpec object to compare. /// /// @return true if \a lhs is less than \a rhs //------------------------------------------------------------------ diff --git a/lldb/include/lldb/Utility/Args.h b/lldb/include/lldb/Utility/Args.h index 4a94f09625d..18344f036d7 100644 --- a/lldb/include/lldb/Utility/Args.h +++ b/lldb/include/lldb/Utility/Args.h @@ -23,14 +23,14 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Args Args.h "lldb/Utility/Args.h" -/// @brief A command line argument class. +/// A command line argument class. /// -/// The Args class is designed to be fed a command line. The -/// command line is copied into an internal buffer and then split up -/// into arguments. Arguments are space delimited if there are no quotes -/// (single, double, or backtick quotes) surrounding the argument. Spaces -/// can be escaped using a \ character to avoid having to surround an -/// argument that contains a space with quotes. +/// The Args class is designed to be fed a command line. The command line is +/// copied into an internal buffer and then split up into arguments. Arguments +/// are space delimited if there are no quotes (single, double, or backtick +/// quotes) surrounding the argument. Spaces can be escaped using a \ +/// character to avoid having to surround an argument that contains a space +/// with quotes. //---------------------------------------------------------------------- class Args { public: @@ -95,18 +95,17 @@ public: //------------------------------------------------------------------ /// Sets the command string contained by this object. /// - /// The command string will be copied and split up into arguments - /// that can be accessed via the accessor functions. + /// The command string will be copied and split up into arguments that can + /// be accessed via the accessor functions. /// /// @param[in] command /// A command StringRef that will be copied and split up /// into arguments. /// /// @see Args::GetArgumentCount() const - /// @see Args::GetArgumentAtIndex (size_t) const - /// @see Args::GetArgumentVector () - /// @see Args::Shift () - /// @see Args::Unshift (const char *) + /// @see Args::GetArgumentAtIndex (size_t) const @see + /// Args::GetArgumentVector () @see Args::Shift () @see Args::Unshift (const + /// char *) //------------------------------------------------------------------ void SetCommandString(llvm::StringRef command); @@ -124,8 +123,8 @@ public: bool empty() const { return GetArgumentCount() == 0; } //------------------------------------------------------------------ - /// Gets the NULL terminated C string argument pointer for the - /// argument at index \a idx. + /// Gets the NULL terminated C string argument pointer for the argument at + /// index \a idx. /// /// @return /// The NULL terminated C string argument pointer if \a idx is a @@ -147,9 +146,9 @@ public: //------------------------------------------------------------------ /// Gets the argument vector. /// - /// The value returned by this function can be used by any function - /// that takes and vector. The return value is just like \a argv - /// in the standard C entry point function: + /// The value returned by this function can be used by any function that + /// takes and vector. The return value is just like \a argv in the standard + /// C entry point function: /// \code /// int main (int argc, const char **argv); /// \endcode @@ -163,9 +162,9 @@ public: //------------------------------------------------------------------ /// Gets the argument vector. /// - /// The value returned by this function can be used by any function - /// that takes and vector. The return value is just like \a argv - /// in the standard C entry point function: + /// The value returned by this function can be used by any function that + /// takes and vector. The return value is just like \a argv in the standard + /// C entry point function: /// \code /// int main (int argc, const char **argv); /// \endcode @@ -219,8 +218,8 @@ public: char quote_char = '\0'); //------------------------------------------------------------------ - /// Replaces the argument value at index \a idx to \a arg_cstr - /// if \a idx is a valid argument index. + /// Replaces the argument value at index \a idx to \a arg_cstr if \a idx is + /// a valid argument index. /// /// @param[in] idx /// The index of the argument that will have its value replaced. @@ -245,11 +244,11 @@ public: void DeleteArgumentAtIndex(size_t idx); //------------------------------------------------------------------ - /// Sets the argument vector value, optionally copying all - /// arguments into an internal buffer. + /// Sets the argument vector value, optionally copying all arguments into an + /// internal buffer. /// - /// Sets the arguments to match those found in \a argv. All argument - /// strings will be copied into an internal buffers. + /// Sets the arguments to match those found in \a argv. All argument strings + /// will be copied into an internal buffers. // // FIXME: Handle the quote character somehow. //------------------------------------------------------------------ @@ -258,21 +257,20 @@ public: void SetArguments(const char **argv); //------------------------------------------------------------------ - /// Shifts the first argument C string value of the array off the - /// argument array. + /// Shifts the first argument C string value of the array off the argument + /// array. /// - /// The string value will be freed, so a copy of the string should - /// be made by calling Args::GetArgumentAtIndex (size_t) const - /// first and copying the returned value before calling - /// Args::Shift(). + /// The string value will be freed, so a copy of the string should be made + /// by calling Args::GetArgumentAtIndex (size_t) const first and copying the + /// returned value before calling Args::Shift(). /// /// @see Args::GetArgumentAtIndex (size_t) const //------------------------------------------------------------------ void Shift(); //------------------------------------------------------------------ - /// Inserts a class owned copy of \a arg_cstr at the beginning of - /// the argument vector. + /// Inserts a class owned copy of \a arg_cstr at the beginning of the + /// argument vector. /// /// A copy \a arg_cstr will be made. /// diff --git a/lldb/include/lldb/Utility/Baton.h b/lldb/include/lldb/Utility/Baton.h index 065f2960962..59999e4697f 100644 --- a/lldb/include/lldb/Utility/Baton.h +++ b/lldb/include/lldb/Utility/Baton.h @@ -23,15 +23,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Baton Baton.h "lldb/Core/Baton.h" -/// @brief A class designed to wrap callback batons so they can cleanup +/// A class designed to wrap callback batons so they can cleanup /// any acquired resources /// -/// This class is designed to be used by any objects that have a -/// callback function that takes a baton where the baton might need to +/// This class is designed to be used by any objects that have a callback +/// function that takes a baton where the baton might need to /// free/delete/close itself. /// -/// The default behavior is to not free anything. Subclasses can -/// free any needed resources in their destructors. +/// The default behavior is to not free anything. Subclasses can free any +/// needed resources in their destructors. //---------------------------------------------------------------------- class Baton { public: diff --git a/lldb/include/lldb/Utility/Connection.h b/lldb/include/lldb/Utility/Connection.h index be5641d5fa6..1b0801378f8 100644 --- a/lldb/include/lldb/Utility/Connection.h +++ b/lldb/include/lldb/Utility/Connection.h @@ -32,16 +32,16 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Connection Connection.h "lldb/Utility/Connection.h" -/// @brief A communication connection class. +/// A communication connection class. /// /// A class that implements that actual communication functions for -/// connecting/disconnecting, reading/writing, and waiting for bytes -/// to become available from a two way communication connection. +/// connecting/disconnecting, reading/writing, and waiting for bytes to become +/// available from a two way communication connection. /// -/// This class is designed to only do very simple communication -/// functions. Instances can be instantiated and given to a -/// Communication class to perform communications where clients can -/// listen for broadcasts, and perform other higher level communications. +/// This class is designed to only do very simple communication functions. +/// Instances can be instantiated and given to a Communication class to +/// perform communications where clients can listen for broadcasts, and +/// perform other higher level communications. //---------------------------------------------------------------------- class Connection { public: @@ -51,8 +51,8 @@ public: Connection() = default; //------------------------------------------------------------------ - /// Virtual destructor since this class gets subclassed and handed - /// to a Communication object. + /// Virtual destructor since this class gets subclassed and handed to a + /// Communication object. //------------------------------------------------------------------ virtual ~Connection(); @@ -79,8 +79,7 @@ public: Status *error_ptr) = 0; //------------------------------------------------------------------ - /// Disconnect the communications connection if one is currently - /// connected. + /// Disconnect the communications connection if one is currently connected. /// /// @param[out] error_ptr /// A pointer to an error object that should be given an @@ -138,8 +137,8 @@ public: lldb::ConnectionStatus &status, Status *error_ptr) = 0; //------------------------------------------------------------------ - /// The actual write function that attempts to write to the - /// communications protocol. + /// The actual write function that attempts to write to the communications + /// protocol. /// /// Subclasses must override this function. /// @@ -190,10 +189,9 @@ public: //------------------------------------------------------------------ /// Returns the underlying IOObject used by the Connection. /// - /// The IOObject can be used to wait for data to become available - /// on the connection. If the Connection does not use IOObjects (and - /// hence does not support waiting) this function should return a - /// null pointer. + /// The IOObject can be used to wait for data to become available on the + /// connection. If the Connection does not use IOObjects (and hence does not + /// support waiting) this function should return a null pointer. /// /// @return /// The underlying IOObject used for reading. diff --git a/lldb/include/lldb/Utility/ConstString.h b/lldb/include/lldb/Utility/ConstString.h index 45c881a215c..98b3447abe3 100644 --- a/lldb/include/lldb/Utility/ConstString.h +++ b/lldb/include/lldb/Utility/ConstString.h @@ -26,17 +26,17 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ConstString ConstString.h "lldb/Utility/ConstString.h" -/// @brief A uniqued constant string class. +/// A uniqued constant string class. /// -/// Provides an efficient way to store strings as uniqued strings. After -/// the strings are uniqued, finding strings that are equal to one -/// another is very fast as just the pointers need to be compared. It -/// also allows for many common strings from many different sources to -/// be shared to keep the memory footprint low. +/// Provides an efficient way to store strings as uniqued strings. After the +/// strings are uniqued, finding strings that are equal to one another is very +/// fast as just the pointers need to be compared. It also allows for many +/// common strings from many different sources to be shared to keep the memory +/// footprint low. /// -/// No reference counting is done on strings that are added to the -/// string pool, once strings are added they are in the string pool for -/// the life of the program. +/// No reference counting is done on strings that are added to the string +/// pool, once strings are added they are in the string pool for the life of +/// the program. //---------------------------------------------------------------------- class ConstString { public: @@ -74,11 +74,10 @@ public: //------------------------------------------------------------------ /// Construct with C String value with max length /// - /// Constructs this object with a C string with a length. If - /// \a max_cstr_len is greater than the actual length of the string, - /// the string length will be truncated. This allows substrings to - /// be created without the need to NULL terminate the string as it - /// is passed into this function. + /// Constructs this object with a C string with a length. If \a max_cstr_len + /// is greater than the actual length of the string, the string length will + /// be truncated. This allows substrings to be created without the need to + /// NULL terminate the string as it is passed into this function. /// /// @param[in] cstr /// A pointer to the first character in the C string. The C @@ -99,8 +98,8 @@ public: //------------------------------------------------------------------ /// Destructor /// - /// Since constant string values are currently not reference counted, - /// there isn't much to do here. + /// Since constant string values are currently not reference counted, there + /// isn't much to do here. //------------------------------------------------------------------ ~ConstString() = default; @@ -112,8 +111,8 @@ public: //-------------------------------------------------------------- /// C equality test. /// - /// Two C strings are equal when they are contained in ConstString - /// objects when their pointer values are equal to each other. + /// Two C strings are equal when they are contained in ConstString objects + /// when their pointer values are equal to each other. /// /// @return /// Returns \b true if the C string in \a lhs is equal to @@ -127,8 +126,8 @@ public: //------------------------------------------------------------------ /// Convert to bool operator. /// - /// This allows code to check a ConstString object to see if it - /// contains a valid string using code such as: + /// This allows code to check a ConstString object to see if it contains a + /// valid string using code such as: /// /// @code /// ConstString str(...); @@ -161,10 +160,9 @@ public: //------------------------------------------------------------------ /// Equal to operator /// - /// Returns true if this string is equal to the string in \a rhs. - /// This operation is very fast as it results in a pointer - /// comparison since all strings are in a uniqued in a global string - /// pool. + /// Returns true if this string is equal to the string in \a rhs. This + /// operation is very fast as it results in a pointer comparison since all + /// strings are in a uniqued in a global string pool. /// /// @param[in] rhs /// Another string object to compare this object to. @@ -182,10 +180,9 @@ public: //------------------------------------------------------------------ /// Not equal to operator /// - /// Returns true if this string is not equal to the string in \a rhs. - /// This operation is very fast as it results in a pointer - /// comparison since all strings are in a uniqued in a global string - /// pool. + /// Returns true if this string is not equal to the string in \a rhs. This + /// operation is very fast as it results in a pointer comparison since all + /// strings are in a uniqued in a global string pool. /// /// @param[in] rhs /// Another string object to compare this object to. @@ -203,8 +200,8 @@ public: //------------------------------------------------------------------ /// Get the string value as a C string. /// - /// Get the value of the contained string as a NULL terminated C - /// string value. + /// Get the value of the contained string as a NULL terminated C string + /// value. /// /// If \a value_if_empty is nullptr, then nullptr will be returned. /// @@ -230,11 +227,10 @@ public: //------------------------------------------------------------------ /// Get the string value as a C string. /// - /// Get the value of the contained string as a NULL terminated C - /// string value. Similar to the ConstString::AsCString() function, - /// yet this function will always return nullptr if the string is not - /// valid. So this function is a direct accessor to the string - /// pointer value. + /// Get the value of the contained string as a NULL terminated C string + /// value. Similar to the ConstString::AsCString() function, yet this + /// function will always return nullptr if the string is not valid. So this + /// function is a direct accessor to the string pointer value. /// /// @return /// Returns nullptr the string is invalid, otherwise the C string @@ -245,8 +241,8 @@ public: //------------------------------------------------------------------ /// Get the length in bytes of string value. /// - /// The string pool stores the length of the string, so we can avoid - /// calling strlen() on the pointer value with this function. + /// The string pool stores the length of the string, so we can avoid calling + /// strlen() on the pointer value with this function. /// /// @return /// Returns the number of bytes that this string occupies in @@ -257,18 +253,18 @@ public: //------------------------------------------------------------------ /// Clear this object's state. /// - /// Clear any contained string and reset the value to the an empty - /// string value. + /// Clear any contained string and reset the value to the an empty string + /// value. //------------------------------------------------------------------ void Clear() { m_string = nullptr; } //------------------------------------------------------------------ /// Equal to operator /// - /// Returns true if this string is equal to the string in \a rhs. - /// If case sensitive equality is tested, this operation is very - /// fast as it results in a pointer comparison since all strings - /// are in a uniqued in a global string pool. + /// Returns true if this string is equal to the string in \a rhs. If case + /// sensitive equality is tested, this operation is very fast as it results + /// in a pointer comparison since all strings are in a uniqued in a global + /// string pool. /// /// @param[in] rhs /// The Left Hand Side const ConstString object reference. @@ -290,13 +286,13 @@ public: //------------------------------------------------------------------ /// Compare two string objects. /// - /// Compares the C string values contained in \a lhs and \a rhs and - /// returns an integer result. + /// Compares the C string values contained in \a lhs and \a rhs and returns + /// an integer result. /// /// NOTE: only call this function when you want a true string - /// comparison. If you want string equality use the, use the == - /// operator as it is much more efficient. Also if you want string - /// inequality, use the != operator for the same reasons. + /// comparison. If you want string equality use the, use the == operator as + /// it is much more efficient. Also if you want string inequality, use the + /// != operator for the same reasons. /// /// @param[in] lhs /// The Left Hand Side const ConstString object reference. @@ -319,10 +315,9 @@ public: //------------------------------------------------------------------ /// Dump the object description to a stream. /// - /// Dump the string value to the stream \a s. If the contained string - /// is empty, print \a value_if_empty to the stream instead. If - /// \a value_if_empty is nullptr, then nothing will be dumped to the - /// stream. + /// Dump the string value to the stream \a s. If the contained string is + /// empty, print \a value_if_empty to the stream instead. If \a + /// value_if_empty is nullptr, then nothing will be dumped to the stream. /// /// @param[in] s /// The stream that will be used to dump the object description. @@ -353,12 +348,12 @@ public: //------------------------------------------------------------------ /// Set the C string value. /// - /// Set the string value in the object by uniquing the \a cstr - /// string value in our global string pool. + /// Set the string value in the object by uniquing the \a cstr string value + /// in our global string pool. /// - /// If the C string already exists in the global string pool, it - /// finds the current entry and returns the existing value. If it - /// doesn't exist, it is added to the string pool. + /// If the C string already exists in the global string pool, it finds the + /// current entry and returns the existing value. If it doesn't exist, it is + /// added to the string pool. /// /// @param[in] cstr /// A NULL terminated C string to add to the string pool. @@ -370,12 +365,12 @@ public: //------------------------------------------------------------------ /// Set the C string value and its mangled counterpart. /// - /// Object files and debug symbols often use mangled string to - /// represent the linkage name for a symbol, function or global. - /// The string pool can efficiently store these values and their - /// counterparts so when we run into another instance of a mangled - /// name, we can avoid calling the name demangler over and over on - /// the same strings and then trying to unique them. + /// Object files and debug symbols often use mangled string to represent the + /// linkage name for a symbol, function or global. The string pool can + /// efficiently store these values and their counterparts so when we run + /// into another instance of a mangled name, we can avoid calling the name + /// demangler over and over on the same strings and then trying to unique + /// them. /// /// @param[in] demangled /// The demangled C string to correlate with the \a mangled @@ -389,15 +384,15 @@ public: const ConstString &mangled); //------------------------------------------------------------------ - /// Retrieve the mangled or demangled counterpart for a mangled - /// or demangled ConstString. + /// Retrieve the mangled or demangled counterpart for a mangled or demangled + /// ConstString. /// - /// Object files and debug symbols often use mangled string to - /// represent the linkage name for a symbol, function or global. - /// The string pool can efficiently store these values and their - /// counterparts so when we run into another instance of a mangled - /// name, we can avoid calling the name demangler over and over on - /// the same strings and then trying to unique them. + /// Object files and debug symbols often use mangled string to represent the + /// linkage name for a symbol, function or global. The string pool can + /// efficiently store these values and their counterparts so when we run + /// into another instance of a mangled name, we can avoid calling the name + /// demangler over and over on the same strings and then trying to unique + /// them. /// /// @param[in] counterpart /// A reference to a ConstString object that might get filled in @@ -413,14 +408,13 @@ public: /// Set the C string value with length. /// /// Set the string value in the object by uniquing \a cstr_len bytes - /// starting at the \a cstr string value in our global string pool. - /// If trim is true, then \a cstr_len indicates a maximum length of - /// the CString and if the actual length of the string is less, then - /// it will be trimmed. + /// starting at the \a cstr string value in our global string pool. If trim + /// is true, then \a cstr_len indicates a maximum length of the CString and + /// if the actual length of the string is less, then it will be trimmed. /// - /// If the C string already exists in the global string pool, it - /// finds the current entry and returns the existing value. If it - /// doesn't exist, it is added to the string pool. + /// If the C string already exists in the global string pool, it finds the + /// current entry and returns the existing value. If it doesn't exist, it is + /// added to the string pool. /// /// @param[in] cstr /// A NULL terminated C string to add to the string pool. @@ -431,20 +425,19 @@ public: void SetCStringWithLength(const char *cstr, size_t cstr_len); //------------------------------------------------------------------ - /// Set the C string value with the minimum length between - /// \a fixed_cstr_len and the actual length of the C string. This - /// can be used for data structures that have a fixed length to - /// store a C string where the string might not be NULL terminated - /// if the string takes the entire buffer. + /// Set the C string value with the minimum length between \a fixed_cstr_len + /// and the actual length of the C string. This can be used for data + /// structures that have a fixed length to store a C string where the string + /// might not be NULL terminated if the string takes the entire buffer. //------------------------------------------------------------------ void SetTrimmedCStringWithLength(const char *cstr, size_t fixed_cstr_len); //------------------------------------------------------------------ /// Get the memory cost of this object. /// - /// Return the size in bytes that this object takes in memory. This - /// returns the size in bytes of this object, which does not include - /// any the shared string values it may refer to. + /// Return the size in bytes that this object takes in memory. This returns + /// the size in bytes of this object, which does not include any the shared + /// string values it may refer to. /// /// @return /// The number of bytes that this object occupies in memory. @@ -456,9 +449,8 @@ public: //------------------------------------------------------------------ /// Get the size in bytes of the current global string pool. /// - /// Reports the size in bytes of all shared C string values, - /// containers and any other values as a byte size for the - /// entire string pool. + /// Reports the size in bytes of all shared C string values, containers and + /// any other values as a byte size for the entire string pool. /// /// @return /// The number of bytes that the global string pool occupies diff --git a/lldb/include/lldb/Utility/DataBuffer.h b/lldb/include/lldb/Utility/DataBuffer.h index ffa71c06be8..05cb6092073 100644 --- a/lldb/include/lldb/Utility/DataBuffer.h +++ b/lldb/include/lldb/Utility/DataBuffer.h @@ -22,39 +22,36 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class DataBuffer DataBuffer.h "lldb/Core/DataBuffer.h" -/// @brief A pure virtual protocol class for abstracted data buffers. +/// A pure virtual protocol class for abstracted data buffers. /// /// DataBuffer is an abstract class that gets packaged into a shared pointer -/// that can use to implement various ways to store data (on the heap, -/// memory mapped, cached inferior memory). It gets used by DataExtractor -/// so many DataExtractor objects can share the same data and sub-ranges -/// of that shared data, and the last object that contains a reference -/// to the shared data will free it. +/// that can use to implement various ways to store data (on the heap, memory +/// mapped, cached inferior memory). It gets used by DataExtractor so many +/// DataExtractor objects can share the same data and sub-ranges of that +/// shared data, and the last object that contains a reference to the shared +/// data will free it. /// /// Subclasses can implement as many different constructors or member -/// functions that allow data to be stored in the object's buffer prior -/// to handing the shared data to clients that use these buffers. +/// functions that allow data to be stored in the object's buffer prior to +/// handing the shared data to clients that use these buffers. /// -/// All subclasses must override all of the pure virtual functions as -/// they are used by clients to access the data. Having a common -/// interface allows different ways of storing data, yet using it in -/// one common way. +/// All subclasses must override all of the pure virtual functions as they are +/// used by clients to access the data. Having a common interface allows +/// different ways of storing data, yet using it in one common way. /// -/// This class currently expects all data to be available without any -/// extra calls being made, but we can modify it to optionally get -/// data on demand with some extra function calls to load the data -/// before it gets accessed. +/// This class currently expects all data to be available without any extra +/// calls being made, but we can modify it to optionally get data on demand +/// with some extra function calls to load the data before it gets accessed. //---------------------------------------------------------------------- class DataBuffer { public: //------------------------------------------------------------------ /// Destructor /// - /// The destructor is virtual as other classes will inherit from - /// this class and be downcast to the DataBuffer pure virtual - /// interface. The virtual destructor ensures that destructing the - /// base class will destruct the class that inherited from it - /// correctly. + /// The destructor is virtual as other classes will inherit from this class + /// and be downcast to the DataBuffer pure virtual interface. The virtual + /// destructor ensures that destructing the base class will destruct the + /// class that inherited from it correctly. //------------------------------------------------------------------ virtual ~DataBuffer() {} diff --git a/lldb/include/lldb/Utility/DataBufferHeap.h b/lldb/include/lldb/Utility/DataBufferHeap.h index 22d3aea2dbb..d64e5b7563a 100644 --- a/lldb/include/lldb/Utility/DataBufferHeap.h +++ b/lldb/include/lldb/Utility/DataBufferHeap.h @@ -21,14 +21,14 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class DataBufferHeap DataBufferHeap.h "lldb/Core/DataBufferHeap.h" -/// @brief A subclass of DataBuffer that stores a data buffer on the heap. +/// A subclass of DataBuffer that stores a data buffer on the heap. /// -/// This class keeps its data in a heap based buffer that is owned by -/// the object. This class is best used to store chunks of data that -/// are created or read from sources that can't intelligently and lazily -/// fault new data pages in. Large amounts of data that comes from files -/// should probably use DataBufferLLVM, which can intelligently determine -/// when memory mapping is optimal. +/// This class keeps its data in a heap based buffer that is owned by the +/// object. This class is best used to store chunks of data that are created +/// or read from sources that can't intelligently and lazily fault new data +/// pages in. Large amounts of data that comes from files should probably use +/// DataBufferLLVM, which can intelligently determine when memory mapping is +/// optimal. //---------------------------------------------------------------------- class DataBufferHeap : public DataBuffer { public: @@ -42,8 +42,7 @@ public: //------------------------------------------------------------------ /// Construct with size \a n and fill with \a ch. /// - /// Initialize this class with \a n bytes and fills the buffer with - /// \a ch. + /// Initialize this class with \a n bytes and fills the buffer with \a ch. /// /// @param[in] n /// The number of bytes that heap based buffer should contain. @@ -67,8 +66,8 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// Virtual destructor since this class inherits from a pure virtual - /// base class #DataBuffer. + /// Virtual destructor since this class inherits from a pure virtual base + /// class #DataBuffer. //------------------------------------------------------------------ ~DataBufferHeap() override; @@ -90,8 +89,8 @@ public: //------------------------------------------------------------------ /// Set the number of bytes in the data buffer. /// - /// Sets the number of bytes that this object should be able to - /// contain. This can be used prior to copying data into the buffer. + /// Sets the number of bytes that this object should be able to contain. + /// This can be used prior to copying data into the buffer. /// /// @param[in] byte_size /// The new size in bytes that this data buffer should attempt diff --git a/lldb/include/lldb/Utility/DataBufferLLVM.h b/lldb/include/lldb/Utility/DataBufferLLVM.h index 0eb229cffbe..d76582cbf47 100644 --- a/lldb/include/lldb/Utility/DataBufferLLVM.h +++ b/lldb/include/lldb/Utility/DataBufferLLVM.h @@ -40,8 +40,8 @@ public: char *GetChars() { return reinterpret_cast<char *>(GetBytes()); } private: - /// \brief Construct a DataBufferLLVM from \p Buffer. \p Buffer must be a - /// valid pointer. + /// Construct a DataBufferLLVM from \p Buffer. \p Buffer must be a valid + /// pointer. explicit DataBufferLLVM(std::unique_ptr<llvm::WritableMemoryBuffer> Buffer); std::unique_ptr<llvm::WritableMemoryBuffer> Buffer; diff --git a/lldb/include/lldb/Utility/DataEncoder.h b/lldb/include/lldb/Utility/DataEncoder.h index ea347d86237..c1214705c72 100644 --- a/lldb/include/lldb/Utility/DataEncoder.h +++ b/lldb/include/lldb/Utility/DataEncoder.h @@ -23,13 +23,12 @@ namespace lldb_private { //---------------------------------------------------------------------- -/// @class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" -/// @brief An binary data encoding class. +/// @class DataEncoder DataEncoder.h "lldb/Core/DataEncoder.h" An binary data +/// encoding class. /// -/// DataEncoder is a class that can encode binary data (swapping if needed) -/// to a data buffer. The data buffer can be caller owned, or can be -/// shared data that can be shared between multiple DataEncoder or -/// DataEncoder instances. +/// DataEncoder is a class that can encode binary data (swapping if needed) to +/// a data buffer. The data buffer can be caller owned, or can be shared data +/// that can be shared between multiple DataEncoder or DataEncoder instances. /// /// @see DataBuffer //---------------------------------------------------------------------- @@ -45,9 +44,8 @@ public: //------------------------------------------------------------------ /// Construct with a buffer that is owned by the caller. /// - /// This constructor allows us to use data that is owned by the - /// caller. The data must stay around as long as this object is - /// valid. + /// This constructor allows us to use data that is owned by the caller. The + /// data must stay around as long as this object is valid. /// /// @param[in] data /// A pointer to caller owned data. @@ -67,10 +65,10 @@ public: //------------------------------------------------------------------ /// Construct with shared data. /// - /// Copies the data shared pointer which adds a reference to the - /// contained in \a data_sp. The shared data reference is reference - /// counted to ensure the data lives as long as anyone still has a - /// valid shared pointer to the data in \a data_sp. + /// Copies the data shared pointer which adds a reference to the contained + /// in \a data_sp. The shared data reference is reference counted to ensure + /// the data lives as long as anyone still has a valid shared pointer to the + /// data in \a data_sp. /// /// @param[in] data_sp /// A shared pointer to data. @@ -87,26 +85,24 @@ public: //------------------------------------------------------------------ /// Destructor /// - /// If this object contains a valid shared data reference, the - /// reference count on the data will be decremented, and if zero, - /// the data will be freed. + /// If this object contains a valid shared data reference, the reference + /// count on the data will be decremented, and if zero, the data will be + /// freed. //------------------------------------------------------------------ ~DataEncoder(); //------------------------------------------------------------------ /// Clears the object state. /// - /// Clears the object contents back to a default invalid state, and - /// release any references to shared data that this object may - /// contain. + /// Clears the object contents back to a default invalid state, and release + /// any references to shared data that this object may contain. //------------------------------------------------------------------ void Clear(); //------------------------------------------------------------------ /// Get the current address size. /// - /// Return the size in bytes of any address values this object will - /// extract. + /// Return the size in bytes of any address values this object will extract. /// /// @return /// The size in bytes of address values that will be extracted. @@ -135,8 +131,7 @@ public: //------------------------------------------------------------------ /// Get the shared data offset. /// - /// Get the offset of the first byte of data in the shared data (if - /// any). + /// Get the offset of the first byte of data in the shared data (if any). /// /// @return /// If this object contains shared data, this function returns @@ -189,11 +184,10 @@ public: //------------------------------------------------------------------ /// Encode an unsigned integer of size \a byte_size to \a offset. /// - /// Encode a single integer value at \a offset and return the offset - /// that follows the newly encoded integer when the data is successfully - /// encoded into the existing data. There must be enough room in the - /// data, else UINT32_MAX will be returned to indicate that encoding - /// failed. + /// Encode a single integer value at \a offset and return the offset that + /// follows the newly encoded integer when the data is successfully encoded + /// into the existing data. There must be enough room in the data, else + /// UINT32_MAX will be returned to indicate that encoding failed. /// /// @param[in] offset /// The offset within the contained data at which to put the @@ -233,15 +227,14 @@ public: uint32_t PutData(uint32_t offset, const void *src, uint32_t src_len); //------------------------------------------------------------------ - /// Encode an address in the existing buffer at \a offset bytes into - /// the buffer. + /// Encode an address in the existing buffer at \a offset bytes into the + /// buffer. /// - /// Encode a single address (honoring the m_addr_size member) to - /// the data and return the next offset where subsequent data would - /// go. - /// pointed to by \a offset_ptr. The size of the extracted address - /// comes from the \a m_addr_size member variable and should be - /// set correctly prior to extracting any address values. + /// Encode a single address (honoring the m_addr_size member) to the data + /// and return the next offset where subsequent data would go. pointed to by + /// \a offset_ptr. The size of the extracted address comes from the \a + /// m_addr_size member variable and should be set correctly prior to + /// extracting any address values. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -259,8 +252,7 @@ public: //------------------------------------------------------------------ /// Put a C string to \a offset. /// - /// Encodes a C string into the existing data including the - /// terminating + /// Encodes a C string into the existing data including the terminating /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -282,8 +274,8 @@ public: //------------------------------------------------------------------ /// Set the address byte size. /// - /// Set the size in bytes that will be used when extracting any - /// address and pointer values from data contained in this object. + /// Set the size in bytes that will be used when extracting any address and + /// pointer values from data contained in this object. /// /// @param[in] addr_size /// The size in bytes to use when extracting addresses. @@ -293,11 +285,10 @@ public: //------------------------------------------------------------------ /// Set data with a buffer that is caller owned. /// - /// Use data that is owned by the caller when extracting values. - /// The data must stay around as long as this object, or any object - /// that copies a subset of this object's data, is valid. If \a - /// bytes is NULL, or \a length is zero, this object will contain - /// no data. + /// Use data that is owned by the caller when extracting values. The data + /// must stay around as long as this object, or any object that copies a + /// subset of this object's data, is valid. If \a bytes is NULL, or \a + /// length is zero, this object will contain no data. /// /// @param[in] bytes /// A pointer to caller owned data. @@ -316,15 +307,14 @@ public: //------------------------------------------------------------------ /// Adopt a subset of shared data in \a data_sp. /// - /// Copies the data shared pointer which adds a reference to the - /// contained in \a data_sp. The shared data reference is reference - /// counted to ensure the data lives as long as anyone still has a - /// valid shared pointer to the data in \a data_sp. The byte order - /// and address byte size settings remain the same. If - /// \a offset is not a valid offset in \a data_sp, then no reference - /// to the shared data will be added. If there are not \a length - /// bytes available in \a data starting at \a offset, the length - /// will be truncated to contains as many bytes as possible. + /// Copies the data shared pointer which adds a reference to the contained + /// in \a data_sp. The shared data reference is reference counted to ensure + /// the data lives as long as anyone still has a valid shared pointer to the + /// data in \a data_sp. The byte order and address byte size settings remain + /// the same. If \a offset is not a valid offset in \a data_sp, then no + /// reference to the shared data will be added. If there are not \a length + /// bytes available in \a data starting at \a offset, the length will be + /// truncated to contains as many bytes as possible. /// /// @param[in] data_sp /// A shared pointer to data. @@ -344,8 +334,8 @@ public: //------------------------------------------------------------------ /// Set the byte_order value. /// - /// Sets the byte order of the data to extract. Extracted values - /// will be swapped if necessary when decoding. + /// Sets the byte order of the data to extract. Extracted values will be + /// swapped if necessary when decoding. /// /// @param[in] byte_order /// The byte order value to use when extracting data. diff --git a/lldb/include/lldb/Utility/DataExtractor.h b/lldb/include/lldb/Utility/DataExtractor.h index 8107a355442..b4886700e1a 100644 --- a/lldb/include/lldb/Utility/DataExtractor.h +++ b/lldb/include/lldb/Utility/DataExtractor.h @@ -34,16 +34,16 @@ template <typename T> class SmallVectorImpl; namespace lldb_private { //---------------------------------------------------------------------- -/// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h" -/// @brief An data extractor class. +/// @class DataExtractor DataExtractor.h "lldb/Core/DataExtractor.h" An data +/// extractor class. /// -/// DataExtractor is a class that can extract data (swapping if needed) -/// from a data buffer. The data buffer can be caller owned, or can be -/// shared data that can be shared between multiple DataExtractor -/// instances. Multiple DataExtractor objects can share the same data, -/// yet extract values in different address sizes and byte order modes. -/// Each object can have a unique position in the shared data and extract -/// data from different offsets. +/// DataExtractor is a class that can extract data (swapping if needed) from a +/// data buffer. The data buffer can be caller owned, or can be shared data +/// that can be shared between multiple DataExtractor instances. Multiple +/// DataExtractor objects can share the same data, yet extract values in +/// different address sizes and byte order modes. Each object can have a +/// unique position in the shared data and extract data from different +/// offsets. /// /// @see DataBuffer //---------------------------------------------------------------------- @@ -51,7 +51,7 @@ class DataExtractor { public: //------------------------------------------------------------------ /// @typedef DataExtractor::Type - /// @brief Type enumerations used in the dump routines. + /// Type enumerations used in the dump routines. //------------------------------------------------------------------ typedef enum { TypeUInt8, ///< Format output as unsigned 8 bit integers @@ -74,9 +74,8 @@ public: //------------------------------------------------------------------ /// Construct with a buffer that is owned by the caller. /// - /// This constructor allows us to use data that is owned by the - /// caller. The data must stay around as long as this object is - /// valid. + /// This constructor allows us to use data that is owned by the caller. The + /// data must stay around as long as this object is valid. /// /// @param[in] data /// A pointer to caller owned data. @@ -100,10 +99,10 @@ public: //------------------------------------------------------------------ /// Construct with shared data. /// - /// Copies the data shared pointer which adds a reference to the - /// contained in \a data_sp. The shared data reference is reference - /// counted to ensure the data lives as long as anyone still has a - /// valid shared pointer to the data in \a data_sp. + /// Copies the data shared pointer which adds a reference to the contained + /// in \a data_sp. The shared data reference is reference counted to ensure + /// the data lives as long as anyone still has a valid shared pointer to the + /// data in \a data_sp. /// /// @param[in] data_sp /// A shared pointer to data. @@ -123,16 +122,14 @@ public: //------------------------------------------------------------------ /// Construct with a subset of \a data. /// - /// Initialize this object with a subset of the data bytes in \a - /// data. If \a data contains shared data, then a reference to the - /// shared data will be added to ensure the shared data stays around - /// as long as any objects have references to the shared data. The - /// byte order value and the address size settings are copied from \a - /// data. If \a offset is not a valid offset in \a data, then no - /// reference to the shared data will be added. If there are not - /// \a length bytes available in \a data starting at \a offset, - /// the length will be truncated to contain as many bytes as - /// possible. + /// Initialize this object with a subset of the data bytes in \a data. If \a + /// data contains shared data, then a reference to the shared data will be + /// added to ensure the shared data stays around as long as any objects have + /// references to the shared data. The byte order value and the address size + /// settings are copied from \a data. If \a offset is not a valid offset in + /// \a data, then no reference to the shared data will be added. If there + /// are not \a length bytes available in \a data starting at \a offset, the + /// length will be truncated to contain as many bytes as possible. /// /// @param[in] data /// Another DataExtractor object that contains data. @@ -155,8 +152,8 @@ public: /// Assignment operator. /// /// Copies all data, byte order and address size settings from \a rhs into - /// this object. If \a rhs contains shared data, a reference to that - /// shared data will be added. + /// this object. If \a rhs contains shared data, a reference to that shared + /// data will be added. /// /// @param[in] rhs /// Another DataExtractor object to copy. @@ -169,9 +166,9 @@ public: //------------------------------------------------------------------ /// Destructor /// - /// If this object contains a valid shared data reference, the - /// reference count on the data will be decremented, and if zero, - /// the data will be freed. + /// If this object contains a valid shared data reference, the reference + /// count on the data will be decremented, and if zero, the data will be + /// freed. //------------------------------------------------------------------ virtual ~DataExtractor(); @@ -180,19 +177,17 @@ public: //------------------------------------------------------------------ /// Clears the object state. /// - /// Clears the object contents back to a default invalid state, and - /// release any references to shared data that this object may - /// contain. + /// Clears the object contents back to a default invalid state, and release + /// any references to shared data that this object may contain. //------------------------------------------------------------------ void Clear(); //------------------------------------------------------------------ - /// Dumps the binary data as \a type objects to stream \a s (or to - /// Log() if \a s is nullptr) starting \a offset bytes into the data - /// and stopping after dumping \a length bytes. The offset into the - /// data is displayed at the beginning of each line and can be - /// offset by base address \a base_addr. \a num_per_line objects - /// will be displayed on each line. + /// Dumps the binary data as \a type objects to stream \a s (or to Log() if + /// \a s is nullptr) starting \a offset bytes into the data and stopping + /// after dumping \a length bytes. The offset into the data is displayed at + /// the beginning of each line and can be offset by base address \a + /// base_addr. \a num_per_line objects will be displayed on each line. /// /// @param[in] s /// The stream to dump the output to. If nullptr the output will @@ -230,8 +225,8 @@ public: //------------------------------------------------------------------ /// Dump a UUID value at \a offset. /// - /// Dump a UUID starting at \a offset bytes into this object's data. - /// If the stream \a s is nullptr, the output will be sent to Log(). + /// Dump a UUID starting at \a offset bytes into this object's data. If the + /// stream \a s is nullptr, the output will be sent to Log(). /// /// @param[in] s /// The stream to dump the output to. If nullptr the output will @@ -244,13 +239,11 @@ public: void DumpUUID(Stream *s, lldb::offset_t offset) const; //------------------------------------------------------------------ - /// Extract an arbitrary number of bytes in the specified byte - /// order. + /// Extract an arbitrary number of bytes in the specified byte order. /// - /// Attemps to extract \a length bytes starting at \a offset bytes - /// into this data in the requested byte order (\a dst_byte_order) - /// and place the results in \a dst. \a dst must be at least \a - /// length bytes long. + /// Attemps to extract \a length bytes starting at \a offset bytes into this + /// data in the requested byte order (\a dst_byte_order) and place the + /// results in \a dst. \a dst must be at least \a length bytes long. /// /// @param[in] offset /// The offset in bytes into the contained data at which to @@ -278,10 +271,10 @@ public: //------------------------------------------------------------------ /// Extract an address from \a *offset_ptr. /// - /// Extract a single address from the data and update the offset - /// pointed to by \a offset_ptr. The size of the extracted address - /// comes from the \a m_addr_size member variable and should be - /// set correctly prior to extracting any address values. + /// Extract a single address from the data and update the offset pointed to + /// by \a offset_ptr. The size of the extracted address comes from the \a + /// m_addr_size member variable and should be set correctly prior to + /// extracting any address values. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -300,8 +293,7 @@ public: //------------------------------------------------------------------ /// Get the current address size. /// - /// Return the size in bytes of any address values this object will - /// extract. + /// Return the size in bytes of any address values this object will extract. /// /// @return /// The size in bytes of address values that will be extracted. @@ -319,11 +311,10 @@ public: //------------------------------------------------------------------ /// Extract a C string from \a *offset_ptr. /// - /// Returns a pointer to a C String from the data at the offset - /// pointed to by \a offset_ptr. A variable length NULL terminated C - /// string will be extracted and the \a offset_ptr will be - /// updated with the offset of the byte that follows the NULL - /// terminator byte. + /// Returns a pointer to a C String from the data at the offset pointed to + /// by \a offset_ptr. A variable length NULL terminated C string will be + /// extracted and the \a offset_ptr will be updated with the offset of the + /// byte that follows the NULL terminator byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -343,8 +334,8 @@ public: //------------------------------------------------------------------ /// Extract a C string from \a *offset_ptr with field size \a len. /// - /// Returns a pointer to a C String from the data at the offset - /// pointed to by \a offset_ptr, with a field length of \a len. + /// Returns a pointer to a C String from the data at the offset pointed to + /// by \a offset_ptr, with a field length of \a len. /// A NULL terminated C string will be extracted and the \a offset_ptr /// will be updated with the offset of the byte that follows the fixed /// length field. @@ -367,10 +358,10 @@ public: //------------------------------------------------------------------ /// Extract \a length bytes from \a *offset_ptr. /// - /// Returns a pointer to a bytes in this object's data at the offset - /// pointed to by \a offset_ptr. If \a length is zero or too large, - /// then the offset pointed to by \a offset_ptr will not be updated - /// and nullptr will be returned. + /// Returns a pointer to a bytes in this object's data at the offset pointed + /// to by \a offset_ptr. If \a length is zero or too large, then the offset + /// pointed to by \a offset_ptr will not be updated and nullptr will be + /// returned. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -414,17 +405,16 @@ public: void *dst) const; //------------------------------------------------------------------ - /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied - /// data is treated as a value that can be swapped to match the - /// specified byte order. + /// Copy \a dst_len bytes from \a *offset_ptr and ensure the copied data is + /// treated as a value that can be swapped to match the specified byte + /// order. /// - /// For values that are larger than the supported integer sizes, - /// this function can be used to extract data in a specified byte - /// order. It can also be used to copy a smaller integer value from - /// to a larger value. The extra bytes left over will be padded - /// correctly according to the byte order of this object and the - /// \a dst_byte_order. This can be very handy when say copying a - /// partial data value into a register. + /// For values that are larger than the supported integer sizes, this + /// function can be used to extract data in a specified byte order. It can + /// also be used to copy a smaller integer value from to a larger value. The + /// extra bytes left over will be padded correctly according to the byte + /// order of this object and the \a dst_byte_order. This can be very handy + /// when say copying a partial data value into a register. /// /// @param[in] src_offset /// The offset into this data from which to start copying an @@ -469,8 +459,7 @@ public: //------------------------------------------------------------------ /// Get the shared data offset. /// - /// Get the offset of the first byte of data in the shared data (if - /// any). + /// Get the offset of the first byte of data in the shared data (if any). /// /// @return /// If this object contains shared data, this function returns @@ -511,10 +500,10 @@ public: //------------------------------------------------------------------ /// Extract an integer of size \a byte_size from \a *offset_ptr. /// - /// Extract a single integer value and update the offset pointed to - /// by \a offset_ptr. The size of the extracted integer is specified - /// by the \a byte_size argument. \a byte_size must have a value - /// >= 1 and <= 4 since the return value is only 32 bits wide. + /// Extract a single integer value and update the offset pointed to by \a + /// offset_ptr. The size of the extracted integer is specified by the \a + /// byte_size argument. \a byte_size must have a value >= 1 and <= 4 since + /// the return value is only 32 bits wide. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -532,14 +521,13 @@ public: uint32_t GetMaxU32(lldb::offset_t *offset_ptr, size_t byte_size) const; //------------------------------------------------------------------ - /// Extract an unsigned integer of size \a byte_size from \a - /// *offset_ptr. + /// Extract an unsigned integer of size \a byte_size from \a *offset_ptr. /// - /// Extract a single unsigned integer value and update the offset - /// pointed to by \a offset_ptr. The size of the extracted integer - /// is specified by the \a byte_size argument. \a byte_size must - /// have a value greater than or equal to one and less than or equal - /// to eight since the return value is 64 bits wide. + /// Extract a single unsigned integer value and update the offset pointed to + /// by \a offset_ptr. The size of the extracted integer is specified by the + /// \a byte_size argument. \a byte_size must have a value greater than or + /// equal to one and less than or equal to eight since the return value is + /// 64 bits wide. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -563,12 +551,11 @@ public: //------------------------------------------------------------------ /// Extract an signed integer of size \a byte_size from \a *offset_ptr. /// - /// Extract a single signed integer value (sign extending if required) - /// and update the offset pointed to by \a offset_ptr. The size of - /// the extracted integer is specified by the \a byte_size argument. - /// \a byte_size must have a value greater than or equal to one and - /// less than or equal to eight since the return value is 64 bits - /// wide. + /// Extract a single signed integer value (sign extending if required) and + /// update the offset pointed to by \a offset_ptr. The size of the extracted + /// integer is specified by the \a byte_size argument. \a byte_size must + /// have a value greater than or equal to one and less than or equal to + /// eight since the return value is 64 bits wide. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -587,15 +574,15 @@ public: int64_t GetMaxS64(lldb::offset_t *offset_ptr, size_t byte_size) const; //------------------------------------------------------------------ - /// Extract an unsigned integer of size \a byte_size from \a - /// *offset_ptr, then extract the bitfield from this value if - /// \a bitfield_bit_size is non-zero. + /// Extract an unsigned integer of size \a byte_size from \a *offset_ptr, + /// then extract the bitfield from this value if \a bitfield_bit_size is + /// non-zero. /// - /// Extract a single unsigned integer value and update the offset - /// pointed to by \a offset_ptr. The size of the extracted integer - /// is specified by the \a byte_size argument. \a byte_size must - /// have a value greater than or equal to one and less than or equal - /// to 8 since the return value is 64 bits wide. + /// Extract a single unsigned integer value and update the offset pointed to + /// by \a offset_ptr. The size of the extracted integer is specified by the + /// \a byte_size argument. \a byte_size must have a value greater than or + /// equal to one and less than or equal to 8 since the return value is 64 + /// bits wide. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -627,16 +614,15 @@ public: uint32_t bitfield_bit_offset) const; //------------------------------------------------------------------ - /// Extract an signed integer of size \a byte_size from \a - /// *offset_ptr, then extract and signe extend the bitfield from - /// this value if \a bitfield_bit_size is non-zero. + /// Extract an signed integer of size \a byte_size from \a *offset_ptr, then + /// extract and signe extend the bitfield from this value if \a + /// bitfield_bit_size is non-zero. /// - /// Extract a single signed integer value (sign extending if required) - /// and update the offset pointed to by \a offset_ptr. The size of - /// the extracted integer is specified by the \a byte_size argument. - /// \a byte_size must have a value greater than or equal to one and - /// less than or equal to eight since the return value is 64 bits - /// wide. + /// Extract a single signed integer value (sign extending if required) and + /// update the offset pointed to by \a offset_ptr. The size of the extracted + /// integer is specified by the \a byte_size argument. \a byte_size must + /// have a value greater than or equal to one and less than or equal to + /// eight since the return value is 64 bits wide. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -670,10 +656,10 @@ public: //------------------------------------------------------------------ /// Extract an pointer from \a *offset_ptr. /// - /// Extract a single pointer from the data and update the offset - /// pointed to by \a offset_ptr. The size of the extracted pointer - /// comes from the \a m_addr_size member variable and should be - /// set correctly prior to extracting any pointer values. + /// Extract a single pointer from the data and update the offset pointed to + /// by \a offset_ptr. The size of the extracted pointer comes from the \a + /// m_addr_size member variable and should be set correctly prior to + /// extracting any pointer values. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -699,8 +685,8 @@ public: //------------------------------------------------------------------ /// Extract a uint8_t value from \a *offset_ptr. /// - /// Extract a single uint8_t from the binary data at the offset - /// pointed to by \a offset_ptr, and advance the offset on success. + /// Extract a single uint8_t from the binary data at the offset pointed to + /// by \a offset_ptr, and advance the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -728,9 +714,9 @@ public: //------------------------------------------------------------------ /// Extract \a count uint8_t values from \a *offset_ptr. /// - /// Extract \a count uint8_t values from the binary data at the - /// offset pointed to by \a offset_ptr, and advance the offset on - /// success. The extracted values are copied into \a dst. + /// Extract \a count uint8_t values from the binary data at the offset + /// pointed to by \a offset_ptr, and advance the offset on success. The + /// extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -755,8 +741,8 @@ public: //------------------------------------------------------------------ /// Extract a uint16_t value from \a *offset_ptr. /// - /// Extract a single uint16_t from the binary data at the offset - /// pointed to by \a offset_ptr, and update the offset on success. + /// Extract a single uint16_t from the binary data at the offset pointed to + /// by \a offset_ptr, and update the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -773,9 +759,9 @@ public: //------------------------------------------------------------------ /// Extract \a count uint16_t values from \a *offset_ptr. /// - /// Extract \a count uint16_t values from the binary data at the - /// offset pointed to by \a offset_ptr, and advance the offset on - /// success. The extracted values are copied into \a dst. + /// Extract \a count uint16_t values from the binary data at the offset + /// pointed to by \a offset_ptr, and advance the offset on success. The + /// extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -800,8 +786,8 @@ public: //------------------------------------------------------------------ /// Extract a uint32_t value from \a *offset_ptr. /// - /// Extract a single uint32_t from the binary data at the offset - /// pointed to by \a offset_ptr, and update the offset on success. + /// Extract a single uint32_t from the binary data at the offset pointed to + /// by \a offset_ptr, and update the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -818,9 +804,9 @@ public: //------------------------------------------------------------------ /// Extract \a count uint32_t values from \a *offset_ptr. /// - /// Extract \a count uint32_t values from the binary data at the - /// offset pointed to by \a offset_ptr, and advance the offset on - /// success. The extracted values are copied into \a dst. + /// Extract \a count uint32_t values from the binary data at the offset + /// pointed to by \a offset_ptr, and advance the offset on success. The + /// extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -845,8 +831,8 @@ public: //------------------------------------------------------------------ /// Extract a uint64_t value from \a *offset_ptr. /// - /// Extract a single uint64_t from the binary data at the offset - /// pointed to by \a offset_ptr, and update the offset on success. + /// Extract a single uint64_t from the binary data at the offset pointed to + /// by \a offset_ptr, and update the offset on success. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -863,9 +849,9 @@ public: //------------------------------------------------------------------ /// Extract \a count uint64_t values from \a *offset_ptr. /// - /// Extract \a count uint64_t values from the binary data at the - /// offset pointed to by \a offset_ptr, and advance the offset on - /// success. The extracted values are copied into \a dst. + /// Extract \a count uint64_t values from the binary data at the offset + /// pointed to by \a offset_ptr, and advance the offset on success. The + /// extracted values are copied into \a dst. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -890,10 +876,10 @@ public: //------------------------------------------------------------------ /// Extract a signed LEB128 value from \a *offset_ptr. /// - /// Extracts an signed LEB128 number from this object's data - /// starting at the offset pointed to by \a offset_ptr. The offset - /// pointed to by \a offset_ptr will be updated with the offset of - /// the byte following the last extracted byte. + /// Extracts an signed LEB128 number from this object's data starting at the + /// offset pointed to by \a offset_ptr. The offset pointed to by \a + /// offset_ptr will be updated with the offset of the byte following the + /// last extracted byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -910,10 +896,10 @@ public: //------------------------------------------------------------------ /// Extract a unsigned LEB128 value from \a *offset_ptr. /// - /// Extracts an unsigned LEB128 number from this object's data - /// starting at the offset pointed to by \a offset_ptr. The offset - /// pointed to by \a offset_ptr will be updated with the offset of - /// the byte following the last extracted byte. + /// Extracts an unsigned LEB128 number from this object's data starting at + /// the offset pointed to by \a offset_ptr. The offset pointed to by \a + /// offset_ptr will be updated with the offset of the byte following the + /// last extracted byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced @@ -932,9 +918,9 @@ public: //------------------------------------------------------------------ /// Peek at a C string at \a offset. /// - /// Peeks at a string in the contained data. No verification is done - /// to make sure the entire string lies within the bounds of this - /// object's data, only \a offset is verified to be a valid offset. + /// Peeks at a string in the contained data. No verification is done to make + /// sure the entire string lies within the bounds of this object's data, + /// only \a offset is verified to be a valid offset. /// /// @param[in] offset /// An offset into the data. @@ -948,8 +934,8 @@ public: //------------------------------------------------------------------ /// Peek at a bytes at \a offset. /// - /// Returns a pointer to \a length bytes at \a offset as long as - /// there are \a length bytes available starting at \a offset. + /// Returns a pointer to \a length bytes at \a offset as long as there are + /// \a length bytes available starting at \a offset. /// /// @return /// A non-nullptr data pointer if \a offset is a valid offset and @@ -965,8 +951,8 @@ public: //------------------------------------------------------------------ /// Set the address byte size. /// - /// Set the size in bytes that will be used when extracting any - /// address and pointer values from data contained in this object. + /// Set the size in bytes that will be used when extracting any address and + /// pointer values from data contained in this object. /// /// @param[in] addr_size /// The size in bytes to use when extracting addresses. @@ -981,11 +967,10 @@ public: //------------------------------------------------------------------ /// Set data with a buffer that is caller owned. /// - /// Use data that is owned by the caller when extracting values. - /// The data must stay around as long as this object, or any object - /// that copies a subset of this object's data, is valid. If \a - /// bytes is nullptr, or \a length is zero, this object will contain - /// no data. + /// Use data that is owned by the caller when extracting values. The data + /// must stay around as long as this object, or any object that copies a + /// subset of this object's data, is valid. If \a bytes is nullptr, or \a + /// length is zero, this object will contain no data. /// /// @param[in] bytes /// A pointer to caller owned data. @@ -1005,16 +990,14 @@ public: //------------------------------------------------------------------ /// Adopt a subset of \a data. /// - /// Set this object's data to be a subset of the data bytes in \a - /// data. If \a data contains shared data, then a reference to the - /// shared data will be added to ensure the shared data stays around - /// as long as any objects have references to the shared data. The - /// byte order and the address size settings are copied from \a - /// data. If \a offset is not a valid offset in \a data, then no - /// reference to the shared data will be added. If there are not - /// \a length bytes available in \a data starting at \a offset, - /// the length will be truncated to contains as many bytes as - /// possible. + /// Set this object's data to be a subset of the data bytes in \a data. If + /// \a data contains shared data, then a reference to the shared data will + /// be added to ensure the shared data stays around as long as any objects + /// have references to the shared data. The byte order and the address size + /// settings are copied from \a data. If \a offset is not a valid offset in + /// \a data, then no reference to the shared data will be added. If there + /// are not \a length bytes available in \a data starting at \a offset, the + /// length will be truncated to contains as many bytes as possible. /// /// @param[in] data /// Another DataExtractor object that contains data. @@ -1034,15 +1017,14 @@ public: //------------------------------------------------------------------ /// Adopt a subset of shared data in \a data_sp. /// - /// Copies the data shared pointer which adds a reference to the - /// contained in \a data_sp. The shared data reference is reference - /// counted to ensure the data lives as long as anyone still has a - /// valid shared pointer to the data in \a data_sp. The byte order - /// and address byte size settings remain the same. If - /// \a offset is not a valid offset in \a data_sp, then no reference - /// to the shared data will be added. If there are not \a length - /// bytes available in \a data starting at \a offset, the length - /// will be truncated to contains as many bytes as possible. + /// Copies the data shared pointer which adds a reference to the contained + /// in \a data_sp. The shared data reference is reference counted to ensure + /// the data lives as long as anyone still has a valid shared pointer to the + /// data in \a data_sp. The byte order and address byte size settings remain + /// the same. If \a offset is not a valid offset in \a data_sp, then no + /// reference to the shared data will be added. If there are not \a length + /// bytes available in \a data starting at \a offset, the length will be + /// truncated to contains as many bytes as possible. /// /// @param[in] data_sp /// A shared pointer to data. @@ -1063,8 +1045,8 @@ public: //------------------------------------------------------------------ /// Set the byte_order value. /// - /// Sets the byte order of the data to extract. Extracted values - /// will be swapped if necessary when decoding. + /// Sets the byte order of the data to extract. Extracted values will be + /// swapped if necessary when decoding. /// /// @param[in] byte_order /// The byte order value to use when extracting data. @@ -1074,10 +1056,10 @@ public: //------------------------------------------------------------------ /// Skip an LEB128 number at \a *offset_ptr. /// - /// Skips a LEB128 number (signed or unsigned) from this object's - /// data starting at the offset pointed to by \a offset_ptr. The - /// offset pointed to by \a offset_ptr will be updated with the - /// offset of the byte following the last extracted byte. + /// Skips a LEB128 number (signed or unsigned) from this object's data + /// starting at the offset pointed to by \a offset_ptr. The offset pointed + /// to by \a offset_ptr will be updated with the offset of the byte + /// following the last extracted byte. /// /// @param[in,out] offset_ptr /// A pointer to an offset within the data that will be advanced diff --git a/lldb/include/lldb/Utility/FileSpec.h b/lldb/include/lldb/Utility/FileSpec.h index 0cf74af81c1..ea02833e531 100644 --- a/lldb/include/lldb/Utility/FileSpec.h +++ b/lldb/include/lldb/Utility/FileSpec.h @@ -43,21 +43,20 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class FileSpec FileSpec.h "lldb/Host/FileSpec.h" -/// @brief A file utility class. +/// A file utility class. /// /// A file specification class that divides paths up into a directory -/// and basename. These string values of the paths are put into uniqued -/// string pools for fast comparisons and efficient memory usage. +/// and basename. These string values of the paths are put into uniqued string +/// pools for fast comparisons and efficient memory usage. /// -/// Another reason the paths are split into the directory and basename -/// is to allow efficient debugger searching. Often in a debugger the -/// user types in the basename of the file, for example setting a -/// breakpoint by file and line, or specifying a module (shared library) -/// to limit the scope in which to execute a command. The user rarely -/// types in a full path. When the paths are already split up, it makes -/// it easy for us to compare only the basenames of a lot of file -/// specifications without having to split up the file path each time -/// to get to the basename. +/// Another reason the paths are split into the directory and basename is to +/// allow efficient debugger searching. Often in a debugger the user types in +/// the basename of the file, for example setting a breakpoint by file and +/// line, or specifying a module (shared library) to limit the scope in which +/// to execute a command. The user rarely types in a full path. When the paths +/// are already split up, it makes it easy for us to compare only the +/// basenames of a lot of file specifications without having to split up the +/// file path each time to get to the basename. //---------------------------------------------------------------------- class FileSpec { public: @@ -72,8 +71,8 @@ public: //------------------------------------------------------------------ /// Constructor with path. /// - /// Takes a path to a file which can be just a filename, or a full - /// path. If \a path is not nullptr or empty, this function will call + /// Takes a path to a file which can be just a filename, or a full path. If + /// \a path is not nullptr or empty, this function will call /// FileSpec::SetFile (const char *path, bool resolve). /// /// @param[in] path @@ -95,8 +94,7 @@ public: //------------------------------------------------------------------ /// Copy constructor /// - /// Makes a copy of the uniqued directory and filename strings from - /// \a rhs. + /// Makes a copy of the uniqued directory and filename strings from \a rhs. /// /// @param[in] rhs /// A const FileSpec object reference to copy. @@ -106,8 +104,8 @@ public: //------------------------------------------------------------------ /// Copy constructor /// - /// Makes a copy of the uniqued directory and filename strings from - /// \a rhs if it is not nullptr. + /// Makes a copy of the uniqued directory and filename strings from \a rhs + /// if it is not nullptr. /// /// @param[in] rhs /// A const FileSpec object pointer to copy if non-nullptr. @@ -126,8 +124,7 @@ public: //------------------------------------------------------------------ /// Assignment operator. /// - /// Makes a copy of the uniqued directory and filename strings from - /// \a rhs. + /// Makes a copy of the uniqued directory and filename strings from \a rhs. /// /// @param[in] rhs /// A const FileSpec object reference to assign to this object. @@ -185,8 +182,8 @@ public: //------------------------------------------------------------------ /// Convert to pointer operator. /// - /// This allows code to check a FileSpec object to see if it - /// contains anything valid using code such as: + /// This allows code to check a FileSpec object to see if it contains + /// anything valid using code such as: /// /// @code /// FileSpec file_spec(...); @@ -203,8 +200,8 @@ public: //------------------------------------------------------------------ /// Logical NOT operator. /// - /// This allows code to check a FileSpec object to see if it is - /// invalid using code such as: + /// This allows code to check a FileSpec object to see if it is invalid + /// using code such as: /// /// @code /// FileSpec file_spec(...); @@ -221,20 +218,19 @@ public: //------------------------------------------------------------------ /// Clears the object state. /// - /// Clear this object by releasing both the directory and filename - /// string values and reverting them to empty strings. + /// Clear this object by releasing both the directory and filename string + /// values and reverting them to empty strings. //------------------------------------------------------------------ void Clear(); //------------------------------------------------------------------ /// Compare two FileSpec objects. /// - /// If \a full is true, then both the directory and the filename - /// must match. If \a full is false, then the directory names for - /// \a lhs and \a rhs are only compared if they are both not empty. - /// This allows a FileSpec object to only contain a filename - /// and it can match FileSpec objects that have matching - /// filenames with different paths. + /// If \a full is true, then both the directory and the filename must match. + /// If \a full is false, then the directory names for \a lhs and \a rhs are + /// only compared if they are both not empty. This allows a FileSpec object + /// to only contain a filename and it can match FileSpec objects that have + /// matching filenames with different paths. /// /// @param[in] lhs /// A const reference to the Left Hand Side object to compare. @@ -270,9 +266,9 @@ public: //------------------------------------------------------------------ /// Dump this object to a Stream. /// - /// Dump the object to the supplied stream \a s. If the object - /// contains a valid directory name, it will be displayed followed - /// by a directory delimiter, and the filename. + /// Dump the object to the supplied stream \a s. If the object contains a + /// valid directory name, it will be displayed followed by a directory + /// delimiter, and the filename. /// /// @param[in] s /// The stream to which to dump the object description. @@ -302,8 +298,8 @@ public: /// Call into the Host to see if it can help find the file (e.g. by /// searching paths set in the environment, etc.). /// - /// If found, sets the value of m_directory to the directory where - /// the file was found. + /// If found, sets the value of m_directory to the directory where the file + /// was found. /// /// @return /// \b true if was able to find the file using expanded search @@ -313,8 +309,8 @@ public: //------------------------------------------------------------------ /// Canonicalize this file path (basically running the static - /// FileSpec::Resolve method on it). Useful if you asked us not to - /// resolve the file path when you set the file. + /// FileSpec::Resolve method on it). Useful if you asked us not to resolve + /// the file path when you set the file. //------------------------------------------------------------------ bool ResolvePath(); @@ -355,9 +351,8 @@ public: const ConstString &GetFilename() const; //------------------------------------------------------------------ - /// Returns true if the filespec represents an implementation source - /// file (files with a ".c", ".cpp", ".m", ".mm" (many more) - /// extension). + /// Returns true if the filespec represents an implementation source file + /// (files with a ".c", ".cpp", ".m", ".mm" (many more) extension). /// /// @return /// \b true if the filespec represents an implementation source @@ -386,9 +381,8 @@ public: //------------------------------------------------------------------ /// Extract the full path to the file. /// - /// Extract the directory and path into a fixed buffer. This is - /// needed as the directory and path are stored in separate string - /// values. + /// Extract the directory and path into a fixed buffer. This is needed as + /// the directory and path are stored in separate string values. /// /// @param[out] path /// The buffer in which to place the extracted full path. @@ -435,10 +429,10 @@ public: //------------------------------------------------------------------ /// Extract the extension of the file. /// - /// Returns a ConstString that represents the extension of the filename - /// for this FileSpec object. If this object does not represent a file, - /// or the filename has no extension, ConstString(nullptr) is returned. - /// The dot ('.') character is not returned as part of the extension + /// Returns a ConstString that represents the extension of the filename for + /// this FileSpec object. If this object does not represent a file, or the + /// filename has no extension, ConstString(nullptr) is returned. The dot + /// ('.') character is not returned as part of the extension /// /// @return /// Returns the extension of the file as a ConstString object. @@ -449,8 +443,8 @@ public: /// Return the filename without the extension part /// /// Returns a ConstString that represents the filename of this object - /// without the extension part (e.g. for a file named "foo.bar", "foo" - /// is returned) + /// without the extension part (e.g. for a file named "foo.bar", "foo" is + /// returned) /// /// @return /// Returns the filename without extension @@ -461,9 +455,8 @@ public: //------------------------------------------------------------------ /// Return the current permissions of the path. /// - /// Returns a bitmask for the current permissions of the file - /// ( zero or more of the permission bits defined in - /// File::Permissions). + /// Returns a bitmask for the current permissions of the file ( zero or more + /// of the permission bits defined in File::Permissions). /// /// @return /// Zero if the file doesn't exist or we are unable to get @@ -475,9 +468,9 @@ public: //------------------------------------------------------------------ /// Get the memory cost of this object. /// - /// Return the size in bytes that this object takes in memory. This - /// returns the size in bytes of this object, not any shared string - /// values it may refer to. + /// Return the size in bytes that this object takes in memory. This returns + /// the size in bytes of this object, not any shared string values it may + /// refer to. /// /// @return /// The number of bytes that this object occupies in memory. @@ -489,9 +482,9 @@ public: //------------------------------------------------------------------ /// Change the file specified with a new path. /// - /// Update the contents of this object with a new path. The path will - /// be split up into a directory and filename and stored as uniqued - /// string values for quick comparison and efficient memory usage. + /// Update the contents of this object with a new path. The path will be + /// split up into a directory and filename and stored as uniqued string + /// values for quick comparison and efficient memory usage. /// /// @param[in] path /// A full, partial, or relative path to a file. @@ -511,11 +504,11 @@ public: //------------------------------------------------------------------ /// Set if the file path has been resolved or not. /// - /// If you know a file path is already resolved and avoided passing - /// a \b true parameter for any functions that take a "bool - /// resolve_path" parameter, you can set the value manually using - /// this call to make sure we don't try and resolve it later, or try - /// and resolve a path that has already been resolved. + /// If you know a file path is already resolved and avoided passing a \b + /// true parameter for any functions that take a "bool resolve_path" + /// parameter, you can set the value manually using this call to make sure + /// we don't try and resolve it later, or try and resolve a path that has + /// already been resolved. /// /// @param[in] is_resolved /// A boolean value that will replace the current value that diff --git a/lldb/include/lldb/Utility/Flags.h b/lldb/include/lldb/Utility/Flags.h index 1b303858b1c..5ef6122d114 100644 --- a/lldb/include/lldb/Utility/Flags.h +++ b/lldb/include/lldb/Utility/Flags.h @@ -17,10 +17,10 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Flags Flags.h "lldb/Utility/Flags.h" -/// @brief A class to manage flags. +/// A class to manage flags. /// -/// The Flags class managed flag bits and allows testing and -/// modification of individual or multiple flag bits. +/// The Flags class managed flag bits and allows testing and modification of +/// individual or multiple flag bits. //---------------------------------------------------------------------- class Flags { public: @@ -32,8 +32,8 @@ public: //---------------------------------------------------------------------- /// Construct with initial flag bit values. /// - /// Constructs this object with \a mask as the initial value for all - /// of the flags. + /// Constructs this object with \a mask as the initial value for all of the + /// flags. /// /// @param[in] mask /// The initial value for all flags. @@ -64,8 +64,7 @@ public: ValueType Get() const { return m_flags; } //---------------------------------------------------------------------- - /// Return the number of flags that can be represented in this - /// object. + /// Return the number of flags that can be represented in this object. /// /// @return /// The maximum number bits in this flag object. @@ -95,8 +94,7 @@ public: } //---------------------------------------------------------------------- - /// Set one or more flags by logical OR'ing \a mask with the current - /// flags. + /// Set one or more flags by logical OR'ing \a mask with the current flags. /// /// @param[in] mask /// A bitfield containing one or more flags. diff --git a/lldb/include/lldb/Utility/History.h b/lldb/include/lldb/Utility/History.h index bbd4b65998b..bf8a6331515 100644 --- a/lldb/include/lldb/Utility/History.h +++ b/lldb/include/lldb/Utility/History.h @@ -28,7 +28,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class HistorySource History.h "lldb/Core/History.h" -/// @brief A class that defines history events. +/// A class that defines history events. //---------------------------------------------------------------------- class HistorySource { @@ -72,11 +72,11 @@ private: //---------------------------------------------------------------------- /// @class HistorySourceUInt History.h "lldb/Core/History.h" -/// @brief A class that defines history events that are represented by +/// A class that defines history events that are represented by /// unsigned integers. /// -/// Any history event that is defined by a unique monotonically -/// increasing unsigned integer +/// Any history event that is defined by a unique monotonically increasing +/// unsigned integer //---------------------------------------------------------------------- class HistorySourceUInt : public HistorySource { diff --git a/lldb/include/lldb/Utility/RegularExpression.h b/lldb/include/lldb/Utility/RegularExpression.h index dba7001ce0f..6048fcc610a 100644 --- a/lldb/include/lldb/Utility/RegularExpression.h +++ b/lldb/include/lldb/Utility/RegularExpression.h @@ -52,11 +52,11 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class RegularExpression RegularExpression.h /// "lldb/Utility/RegularExpression.h" -/// @brief A C++ wrapper class for regex. +/// A C++ wrapper class for regex. /// -/// This regular expression class wraps the posix regex functions -/// \c regcomp(), \c regerror(), \c regexec(), and \c regfree() from -/// the header file in \c /usr/include/regex\.h. +/// This regular expression class wraps the posix regex functions \c +/// regcomp(), \c regerror(), \c regexec(), and \c regfree() from the header +/// file in \c /usr/include/regex\.h. //---------------------------------------------------------------------- class RegularExpression { public: @@ -98,8 +98,8 @@ public: //------------------------------------------------------------------ /// Default constructor. /// - /// The default constructor that initializes the object state such - /// that it contains no compiled regular expression. + /// The default constructor that initializes the object state such that it + /// contains no compiled regular expression. //------------------------------------------------------------------ RegularExpression(); @@ -108,8 +108,8 @@ public: //------------------------------------------------------------------ /// Destructor. /// - /// Any previously compiled regular expression contained in this - /// object will be freed. + /// Any previously compiled regular expression contained in this object will + /// be freed. //------------------------------------------------------------------ ~RegularExpression(); @@ -120,12 +120,11 @@ public: //------------------------------------------------------------------ /// Compile a regular expression. /// - /// Compile a regular expression using the supplied regular - /// expression text. The compiled regular expression lives - /// in this object so that it can be readily used for regular - /// expression matches. Execute() can be called after the regular - /// expression is compiled. Any previously compiled regular - /// expression contained in this object will be freed. + /// Compile a regular expression using the supplied regular expression text. + /// The compiled regular expression lives in this object so that it can be + /// readily used for regular expression matches. Execute() can be called + /// after the regular expression is compiled. Any previously compiled + /// regular expression contained in this object will be freed. /// /// @param[in] re /// A NULL terminated C string that represents the regular @@ -141,11 +140,11 @@ public: //------------------------------------------------------------------ /// Executes a regular expression. /// - /// Execute a regular expression match using the compiled regular - /// expression that is already in this object against the match - /// string \a s. If any parens are used for regular expression - /// matches \a match_count should indicate the number of regmatch_t - /// values that are present in \a match_ptr. + /// Execute a regular expression match using the compiled regular expression + /// that is already in this object against the match string \a s. If any + /// parens are used for regular expression matches \a match_count should + /// indicate the number of regmatch_t values that are present in \a + /// match_ptr. /// /// @param[in] string /// The string to match against the compile regular expression. @@ -167,8 +166,8 @@ public: //------------------------------------------------------------------ /// Free the compiled regular expression. /// - /// If this object contains a valid compiled regular expression, - /// this function will free any resources it was consuming. + /// If this object contains a valid compiled regular expression, this + /// function will free any resources it was consuming. //------------------------------------------------------------------ void Free(); diff --git a/lldb/include/lldb/Utility/Status.h b/lldb/include/lldb/Utility/Status.h index 8c3e009a8c2..3bd2cd5b3b4 100644 --- a/lldb/include/lldb/Utility/Status.h +++ b/lldb/include/lldb/Utility/Status.h @@ -28,30 +28,27 @@ class raw_ostream; namespace lldb_private { //---------------------------------------------------------------------- -/// @class Status Status.h "lldb/Utility/Status.h" -/// @brief An error handling class. +/// @class Status Status.h "lldb/Utility/Status.h" An error handling class. /// /// This class is designed to be able to hold any error code that can be -/// encountered on a given platform. The errors are stored as a value -/// of type Status::ValueType. This value should be large enough to hold -/// any and all errors that the class supports. Each error has an -/// associated type that is of type lldb::ErrorType. New types -/// can be added to support new error types, and architecture specific -/// types can be enabled. In the future we may wish to switch to a -/// registration mechanism where new error types can be registered at -/// runtime instead of a hard coded scheme. +/// encountered on a given platform. The errors are stored as a value of type +/// Status::ValueType. This value should be large enough to hold any and all +/// errors that the class supports. Each error has an associated type that is +/// of type lldb::ErrorType. New types can be added to support new error +/// types, and architecture specific types can be enabled. In the future we +/// may wish to switch to a registration mechanism where new error types can +/// be registered at runtime instead of a hard coded scheme. /// -/// All errors in this class also know how to generate a string -/// representation of themselves for printing results and error codes. -/// The string value will be fetched on demand and its string value will -/// be cached until the error is cleared of the value of the error -/// changes. +/// All errors in this class also know how to generate a string representation +/// of themselves for printing results and error codes. The string value will +/// be fetched on demand and its string value will be cached until the error +/// is cleared of the value of the error changes. //---------------------------------------------------------------------- class Status { public: //------------------------------------------------------------------ - /// Every error value that this object can contain needs to be able - /// to fit into ValueType. + /// Every error value that this object can contain needs to be able to fit + /// into ValueType. //------------------------------------------------------------------ typedef uint32_t ValueType; @@ -98,11 +95,10 @@ public: //------------------------------------------------------------------ /// Get the error string associated with the current error. // - /// Gets the error value as a NULL terminated C string. The error - /// string will be fetched and cached on demand. The error string - /// will be retrieved from a callback that is appropriate for the - /// type of the error and will be cached until the error value is - /// changed or cleared. + /// Gets the error value as a NULL terminated C string. The error string + /// will be fetched and cached on demand. The error string will be retrieved + /// from a callback that is appropriate for the type of the error and will + /// be cached until the error value is changed or cleared. /// /// @return /// The error as a NULL terminated C string value if the error @@ -114,8 +110,8 @@ public: //------------------------------------------------------------------ /// Clear the object state. /// - /// Reverts the state of this object to contain a generic success - /// value and frees any cached error string value. + /// Reverts the state of this object to contain a generic success value and + /// frees any cached error string value. //------------------------------------------------------------------ void Clear(); @@ -147,8 +143,8 @@ public: //------------------------------------------------------------------ /// Set accessor from a kern_return_t. /// - /// Set accesssor for the error value to \a err and the error type - /// to \c MachKernel. + /// Set accesssor for the error value to \a err and the error type to \c + /// MachKernel. /// /// @param[in] err /// A mach error code. @@ -163,8 +159,8 @@ public: //------------------------------------------------------------------ /// Set accesssor with an error value and type. /// - /// Set accesssor for the error value to \a err and the error type - /// to \a type. + /// Set accesssor for the error value to \a err and the error type to \a + /// type. /// /// @param[in] err /// A mach error code. @@ -177,28 +173,28 @@ public: //------------------------------------------------------------------ /// Set the current error to errno. /// - /// Update the error value to be \c errno and update the type to - /// be \c Status::POSIX. + /// Update the error value to be \c errno and update the type to be \c + /// Status::POSIX. //------------------------------------------------------------------ void SetErrorToErrno(); //------------------------------------------------------------------ /// Set the current error to a generic error. /// - /// Update the error value to be \c LLDB_GENERIC_ERROR and update the - /// type to be \c Status::Generic. + /// Update the error value to be \c LLDB_GENERIC_ERROR and update the type + /// to be \c Status::Generic. //------------------------------------------------------------------ void SetErrorToGenericError(); //------------------------------------------------------------------ /// Set the current error string to \a err_str. /// - /// Set accessor for the error string value for a generic errors, - /// or to supply additional details above and beyond the standard - /// error strings that the standard type callbacks typically - /// provide. This allows custom strings to be supplied as an - /// error explanation. The error string value will remain until the - /// error value is cleared or a new error value/type is assigned. + /// Set accessor for the error string value for a generic errors, or to + /// supply additional details above and beyond the standard error strings + /// that the standard type callbacks typically provide. This allows custom + /// strings to be supplied as an error explanation. The error string value + /// will remain until the error value is cleared or a new error value/type + /// is assigned. /// /// @param err_str /// The new custom error string to copy and cache. @@ -224,8 +220,8 @@ public: //------------------------------------------------------------------ /// Test for success condition. /// - /// Returns true if the error code in this object is considered a - /// successful return value. + /// Returns true if the error code in this object is considered a successful + /// return value. /// /// @return /// \b true if this object contains an value that describes @@ -236,8 +232,8 @@ public: //------------------------------------------------------------------ /// Test for a failure due to a generic interrupt. /// - /// Returns true if the error code in this object was caused by an interrupt. - /// At present only supports Posix EINTR. + /// Returns true if the error code in this object was caused by an + /// interrupt. At present only supports Posix EINTR. /// /// @return /// \b true if this object contains an value that describes diff --git a/lldb/include/lldb/Utility/Stream.h b/lldb/include/lldb/Utility/Stream.h index 3cfb173b225..bf837749fa3 100644 --- a/lldb/include/lldb/Utility/Stream.h +++ b/lldb/include/lldb/Utility/Stream.h @@ -25,7 +25,7 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class Stream Stream.h "lldb/Utility/Stream.h" -/// @brief A stream class that can stream formatted output to a file. +/// A stream class that can stream formatted output to a file. //---------------------------------------------------------------------- class Stream { public: @@ -40,15 +40,14 @@ public: //------------------------------------------------------------------ /// Construct with flags and address size and byte order. /// - /// Construct with dump flags \a flags and the default address - /// size. \a flags can be any of the above enumeration logical OR'ed - /// together. + /// Construct with dump flags \a flags and the default address size. \a + /// flags can be any of the above enumeration logical OR'ed together. //------------------------------------------------------------------ Stream(uint32_t flags, uint32_t addr_size, lldb::ByteOrder byte_order); //------------------------------------------------------------------ - /// Construct a default Stream, not binary, host byte order and - /// host addr size. + /// Construct a default Stream, not binary, host byte order and host addr + /// size. /// //------------------------------------------------------------------ Stream(); @@ -65,16 +64,15 @@ public: //------------------------------------------------------------------ /// Flush the stream. /// - /// Subclasses should flush the stream to make any output appear - /// if the stream has any buffering. + /// Subclasses should flush the stream to make any output appear if the + /// stream has any buffering. //------------------------------------------------------------------ virtual void Flush() = 0; //------------------------------------------------------------------ /// Output character bytes to the stream. /// - /// Appends \a src_len characters from the buffer \a src to the - /// stream. + /// Appends \a src_len characters from the buffer \a src to the stream. /// /// @param[in] src /// A buffer containing at least \a src_len bytes of data. @@ -95,8 +93,8 @@ public: //------------------------------------------------------------------ /// Set the byte_order value. /// - /// Sets the byte order of the data to extract. Extracted values - /// will be swapped if necessary when decoding. + /// Sets the byte order of the data to extract. Extracted values will be + /// swapped if necessary when decoding. /// /// @param[in] byte_order /// The byte order value to use when extracting data. @@ -107,9 +105,8 @@ public: lldb::ByteOrder SetByteOrder(lldb::ByteOrder byte_order); //------------------------------------------------------------------ - /// Format a C string from a printf style format and variable - /// arguments and encode and append the resulting C string as hex - /// bytes. + /// Format a C string from a printf style format and variable arguments and + /// encode and append the resulting C string as hex bytes. /// /// @param[in] format /// A printf style format string. @@ -124,9 +121,8 @@ public: __attribute__((__format__(__printf__, 2, 3))); //------------------------------------------------------------------ - /// Format a C string from a printf style format and variable - /// arguments and encode and append the resulting C string as hex - /// bytes. + /// Format a C string from a printf style format and variable arguments and + /// encode and append the resulting C string as hex bytes. /// /// @param[in] format /// A printf style format string. @@ -314,8 +310,8 @@ public: //------------------------------------------------------------------ /// Output an address value to this stream. /// - /// Put an address \a addr out to the stream with optional \a prefix - /// and \a suffix strings. + /// Put an address \a addr out to the stream with optional \a prefix and \a + /// suffix strings. /// /// @param[in] addr /// An address value. @@ -335,8 +331,8 @@ public: //------------------------------------------------------------------ /// Output an address range to this stream. /// - /// Put an address range \a lo_addr - \a hi_addr out to the stream - /// with optional \a prefix and \a suffix strings. + /// Put an address range \a lo_addr - \a hi_addr out to the stream with + /// optional \a prefix and \a suffix strings. /// /// @param[in] lo_addr /// The start address of the address range. @@ -415,8 +411,8 @@ public: //------------------------------------------------------------------ /// Indent the current line in the stream. /// - /// Indent the current line using the current indentation level and - /// print an optional string following the indentation spaces. + /// Indent the current line using the current indentation level and print an + /// optional string following the indentation spaces. /// /// @param[in] s /// A C string to print following the indentation. If nullptr, just @@ -438,8 +434,8 @@ public: //------------------------------------------------------------------ /// Output an offset value. /// - /// Put an offset \a uval out to the stream using the printf format - /// in \a format. + /// Put an offset \a uval out to the stream using the printf format in \a + /// format. /// /// @param[in] offset /// The offset value. @@ -472,8 +468,8 @@ public: //------------------------------------------------------------------ /// Output a quoted C string value to the stream. /// - /// Print a double quoted NULL terminated C string to the stream - /// using the printf format in \a format. + /// Print a double quoted NULL terminated C string to the stream using the + /// printf format in \a format. /// /// @param[in] cstr /// A NULL terminated C string value. @@ -503,8 +499,8 @@ public: //------------------------------------------------------------------ /// Output a SLEB128 number to the stream. /// - /// Put an SLEB128 \a uval out to the stream using the printf format - /// in \a format. + /// Put an SLEB128 \a uval out to the stream using the printf format in \a + /// format. /// /// @param[in] uval /// A uint64_t value that was extracted as a SLEB128 value. @@ -517,8 +513,8 @@ public: //------------------------------------------------------------------ /// Output a ULEB128 number to the stream. /// - /// Put an ULEB128 \a uval out to the stream using the printf format - /// in \a format. + /// Put an ULEB128 \a uval out to the stream using the printf format in \a + /// format. /// /// @param[in] uval /// A uint64_t value that was extracted as a ULEB128 value. diff --git a/lldb/include/lldb/Utility/StructuredData.h b/lldb/include/lldb/Utility/StructuredData.h index 2ea5fb98e05..d3ebab16f51 100644 --- a/lldb/include/lldb/Utility/StructuredData.h +++ b/lldb/include/lldb/Utility/StructuredData.h @@ -38,17 +38,17 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class StructuredData StructuredData.h "lldb/Utility/StructuredData.h" -/// @brief A class which can hold structured data +/// A class which can hold structured data /// -/// The StructuredData class is designed to hold the data from a JSON -/// or plist style file -- a serialized data structure with dictionaries -/// (maps, hashes), arrays, and concrete values like integers, floating -/// point numbers, strings, booleans. +/// The StructuredData class is designed to hold the data from a JSON or plist +/// style file -- a serialized data structure with dictionaries (maps, +/// hashes), arrays, and concrete values like integers, floating point +/// numbers, strings, booleans. /// -/// StructuredData does not presuppose any knowledge of the schema for -/// the data it is holding; it can parse JSON data, for instance, and -/// other parts of lldb can iterate through the parsed data set to find -/// keys and values that may be present. +/// StructuredData does not presuppose any knowledge of the schema for the +/// data it is holding; it can parse JSON data, for instance, and other parts +/// of lldb can iterate through the parsed data set to find keys and values +/// that may be present. //---------------------------------------------------------------------- class StructuredData { diff --git a/lldb/include/lldb/Utility/TildeExpressionResolver.h b/lldb/include/lldb/Utility/TildeExpressionResolver.h index 84620320c7a..ae6b4073f6a 100644 --- a/lldb/include/lldb/Utility/TildeExpressionResolver.h +++ b/lldb/include/lldb/Utility/TildeExpressionResolver.h @@ -22,7 +22,7 @@ class TildeExpressionResolver { public: virtual ~TildeExpressionResolver(); - /// \brief Resolve a Tilde Expression contained according to bash rules. + /// Resolve a Tilde Expression contained according to bash rules. /// /// \param Expr Contains the tilde expression to resolve. A valid tilde /// expression must begin with a tilde and contain only non @@ -35,7 +35,7 @@ public: virtual bool ResolveExact(llvm::StringRef Expr, llvm::SmallVectorImpl<char> &Output) = 0; - /// \brief Auto-complete a tilde expression with all matching values. + /// Auto-complete a tilde expression with all matching values. /// /// \param Expr Contains the tilde expression prefix to resolve. See /// ResolveExact() for validity rules. @@ -48,8 +48,8 @@ public: virtual bool ResolvePartial(llvm::StringRef Expr, llvm::StringSet<> &Output) = 0; - /// \brief Resolve an entire path that begins with a tilde expression, - /// replacing the username portion with the matched result. + /// Resolve an entire path that begins with a tilde expression, replacing + /// the username portion with the matched result. bool ResolveFullPath(llvm::StringRef Expr, llvm::SmallVectorImpl<char> &Output); }; diff --git a/lldb/include/lldb/Utility/Timer.h b/lldb/include/lldb/Utility/Timer.h index c06ac17d344..2c1e984837c 100644 --- a/lldb/include/lldb/Utility/Timer.h +++ b/lldb/include/lldb/Utility/Timer.h @@ -20,7 +20,7 @@ class Stream; //---------------------------------------------------------------------- /// @class Timer Timer.h "lldb/Utility/Timer.h" -/// @brief A timer class that simplifies common timing metrics. +/// A timer class that simplifies common timing metrics. //---------------------------------------------------------------------- class Timer { diff --git a/lldb/include/lldb/Utility/UserID.h b/lldb/include/lldb/Utility/UserID.h index b178efd44fe..9e15e6a43c6 100644 --- a/lldb/include/lldb/Utility/UserID.h +++ b/lldb/include/lldb/Utility/UserID.h @@ -20,14 +20,14 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class UserID UserID.h "lldb/Core/UserID.h" -/// @brief A mix in class that contains a generic user ID. +/// A mix in class that contains a generic user ID. /// -/// UserID is designed as a mix in class that can contain an integer -/// based unique identifier for a variety of objects in lldb. +/// UserID is designed as a mix in class that can contain an integer based +/// unique identifier for a variety of objects in lldb. /// -/// The value for this identifier is chosen by each parser plug-in. A -/// value should be chosen that makes sense for each kind of object -/// and should allow quick access to further and more in depth parsing. +/// The value for this identifier is chosen by each parser plug-in. A value +/// should be chosen that makes sense for each kind of object and should allow +/// quick access to further and more in depth parsing. /// /// Symbol table entries can use this to store the original symbol table /// index, functions can use it to store the symbol table index or the @@ -68,11 +68,9 @@ struct UserID { void SetID(lldb::user_id_t uid) { m_uid = uid; } //------------------------------------------------------------------ - /// Unary predicate function object that can search for a matching - /// user ID. + /// Unary predicate function object that can search for a matching user ID. /// - /// Function object that can be used on any class that inherits - /// from UserID: + /// Function object that can be used on any class that inherits from UserID: /// \code /// iterator pos; /// pos = std::find_if (coll.begin(), coll.end(), UserID::IDMatches(blockID)); diff --git a/lldb/include/lldb/lldb-private-defines.h b/lldb/include/lldb/lldb-private-defines.h index 22172366c25..9b6594422e8 100644 --- a/lldb/include/lldb/lldb-private-defines.h +++ b/lldb/include/lldb/lldb-private-defines.h @@ -23,7 +23,7 @@ #endif /// \macro LLVM_FALLTHROUGH -/// \brief Marks an empty statement preceding a deliberate switch fallthrough. +/// Marks an empty statement preceding a deliberate switch fallthrough. #if __has_cpp_attribute(clang::fallthrough) #define LLVM_FALLTHROUGH [[clang::fallthrough]] #else diff --git a/lldb/source/Expression/IRDynamicChecks.cpp b/lldb/source/Expression/IRDynamicChecks.cpp index 0c8cba2050c..e0a7dca4113 100644 --- a/lldb/source/Expression/IRDynamicChecks.cpp +++ b/lldb/source/Expression/IRDynamicChecks.cpp @@ -109,17 +109,17 @@ static std::string PrintValue(llvm::Value *V, bool truncate = false) { //---------------------------------------------------------------------- /// @class Instrumenter IRDynamicChecks.cpp -/// @brief Finds and instruments individual LLVM IR instructions +/// Finds and instruments individual LLVM IR instructions /// -/// When instrumenting LLVM IR, it is frequently desirable to first search -/// for instructions, and then later modify them. This way iterators -/// remain intact, and multiple passes can look at the same code base without +/// When instrumenting LLVM IR, it is frequently desirable to first search for +/// instructions, and then later modify them. This way iterators remain +/// intact, and multiple passes can look at the same code base without /// treading on each other's toes. /// /// The Instrumenter class implements this functionality. A client first -/// calls Inspect on a function, which populates a list of instructions to -/// be instrumented. Then, later, when all passes' Inspect functions have -/// been called, the client calls Instrument, which adds the desired +/// calls Inspect on a function, which populates a list of instructions to be +/// instrumented. Then, later, when all passes' Inspect functions have been +/// called, the client calls Instrument, which adds the desired /// instrumentation. /// /// A subclass of Instrumenter must override InstrumentInstruction, which @@ -200,8 +200,8 @@ protected: } //------------------------------------------------------------------ - /// Determine whether a single instruction is interesting to - /// instrument, and, if so, call RegisterInstruction + /// Determine whether a single instruction is interesting to instrument, + /// and, if so, call RegisterInstruction /// /// @param[in] i /// The instruction to be inspected. @@ -250,8 +250,8 @@ protected: } //------------------------------------------------------------------ - /// Build a function pointer for a function with signature - /// void (*)(uint8_t*) with a given address + /// Build a function pointer for a function with signature void + /// (*)(uint8_t*) with a given address /// /// @param[in] start_address /// The address of the function. @@ -275,8 +275,8 @@ protected: } //------------------------------------------------------------------ - /// Build a function pointer for a function with signature - /// void (*)(uint8_t*, uint8_t*) with a given address + /// Build a function pointer for a function with signature void + /// (*)(uint8_t*, uint8_t*) with a given address /// /// @param[in] start_address /// The address of the function. diff --git a/lldb/source/Plugins/DynamicLoader/Hexagon-DYLD/HexagonDYLDRendezvous.h b/lldb/source/Plugins/DynamicLoader/Hexagon-DYLD/HexagonDYLDRendezvous.h index b68f89b9ce8..9e7129461f0 100644 --- a/lldb/source/Plugins/DynamicLoader/Hexagon-DYLD/HexagonDYLDRendezvous.h +++ b/lldb/source/Plugins/DynamicLoader/Hexagon-DYLD/HexagonDYLDRendezvous.h @@ -24,12 +24,12 @@ class Process; } /// @class HexagonDYLDRendezvous -/// @brief Interface to the runtime linker. +/// Interface to the runtime linker. /// /// A structure is present in a processes memory space which is updated by the -/// runtime liker each time a module is loaded or unloaded. This class provides -/// an interface to this structure and maintains a consistent snapshot of the -/// currently loaded modules. +/// runtime liker each time a module is loaded or unloaded. This class +/// provides an interface to this structure and maintains a consistent +/// snapshot of the currently loaded modules. class HexagonDYLDRendezvous { // This structure is used to hold the contents of the debug rendezvous @@ -124,7 +124,7 @@ public: void DumpToLog(lldb_private::Log *log) const; - /// @brief Constants describing the state of the rendezvous. + /// Constants describing the state of the rendezvous. /// /// @see GetState(). enum RendezvousState { @@ -133,8 +133,8 @@ public: eDelete, }; - /// @brief Structure representing the shared objects currently loaded into - /// the inferior process. + /// Structure representing the shared objects currently loaded into the + /// inferior process. /// /// This object is a rough analogue to the struct link_map object which /// actually lives in the inferiors memory. @@ -198,7 +198,8 @@ protected: /// List of SOEntry objects corresponding to the current link map state. SOEntryList m_soentries; - /// List of SOEntry's added to the link map since the last call to Resolve(). + /// List of SOEntry's added to the link map since the last call to + /// Resolve(). SOEntryList m_added_soentries; /// List of SOEntry's removed from the link map since the last call to diff --git a/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/AuxVector.h b/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/AuxVector.h index cf9da080835..3b06fe18f0c 100644 --- a/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/AuxVector.h +++ b/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/AuxVector.h @@ -22,12 +22,12 @@ class DataExtractor; } /// @class AuxVector -/// @brief Represents a processes auxiliary vector. +/// Represents a processes auxiliary vector. /// /// When a process is loaded on Linux a vector of values is placed onto the -/// stack communicating operating system specific information. On construction -/// this class locates and parses this information and provides a simple -/// read-only interface to the entries found. +/// stack communicating operating system specific information. On +/// construction this class locates and parses this information and provides a +/// simple read-only interface to the entries found. class AuxVector { public: @@ -41,8 +41,9 @@ public: }; /// Constants describing the type of entry. - /// On Linux, running "LD_SHOW_AUXV=1 ./executable" will spew AUX information. - /// Added AUXV prefix to avoid potential conflicts with system-defined macros + /// On Linux, running "LD_SHOW_AUXV=1 ./executable" will spew AUX + /// information. Added AUXV prefix to avoid potential conflicts with system- + /// defined macros enum EntryType { AUXV_AT_NULL = 0, ///< End of auxv. AUXV_AT_IGNORE = 1, ///< Ignore entry. diff --git a/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/DYLDRendezvous.h b/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/DYLDRendezvous.h index 295ae55e1b8..a7071801f56 100644 --- a/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/DYLDRendezvous.h +++ b/lldb/source/Plugins/DynamicLoader/POSIX-DYLD/DYLDRendezvous.h @@ -29,12 +29,12 @@ class Process; } /// @class DYLDRendezvous -/// @brief Interface to the runtime linker. +/// Interface to the runtime linker. /// /// A structure is present in a processes memory space which is updated by the -/// runtime liker each time a module is loaded or unloaded. This class provides -/// an interface to this structure and maintains a consistent snapshot of the -/// currently loaded modules. +/// runtime liker each time a module is loaded or unloaded. This class +/// provides an interface to this structure and maintains a consistent +/// snapshot of the currently loaded modules. class DYLDRendezvous { // This structure is used to hold the contents of the debug rendezvous @@ -119,13 +119,13 @@ public: void DumpToLog(lldb_private::Log *log) const; - /// @brief Constants describing the state of the rendezvous. + /// Constants describing the state of the rendezvous. /// /// @see GetState(). enum RendezvousState { eConsistent, eAdd, eDelete }; - /// @brief Structure representing the shared objects currently loaded into - /// the inferior process. + /// Structure representing the shared objects currently loaded into the + /// inferior process. /// /// This object is a rough analogue to the struct link_map object which /// actually lives in the inferiors memory. @@ -194,7 +194,8 @@ protected: /// List of SOEntry objects corresponding to the current link map state. SOEntryList m_soentries; - /// List of SOEntry's added to the link map since the last call to Resolve(). + /// List of SOEntry's added to the link map since the last call to + /// Resolve(). SOEntryList m_added_soentries; /// List of SOEntry's removed from the link map since the last call to diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ASTResultSynthesizer.h b/lldb/source/Plugins/ExpressionParser/Clang/ASTResultSynthesizer.h index c0e6c0358a2..859a1dfa5f7 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ASTResultSynthesizer.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ASTResultSynthesizer.h @@ -18,18 +18,17 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ASTResultSynthesizer ASTResultSynthesizer.h -/// "lldb/Expression/ASTResultSynthesizer.h" -/// @brief Adds a result variable declaration to the ASTs for an expression. +/// "lldb/Expression/ASTResultSynthesizer.h" Adds a result variable +/// declaration to the ASTs for an expression. /// /// Users expect the expression "i + 3" to return a result, even if a result /// variable wasn't specifically declared. To fulfil this requirement, LLDB -/// adds -/// a result variable to the expression, transforming it to -/// "int $__lldb_expr_result = i + 3." The IR transformers ensure that the +/// adds a result variable to the expression, transforming it to "int +/// $__lldb_expr_result = i + 3." The IR transformers ensure that the /// resulting variable is mapped to the right piece of memory. -/// ASTResultSynthesizer's job is to add the variable and its initialization to -/// the ASTs for the expression, and it does so by acting as a SemaConsumer for -/// Clang. +/// ASTResultSynthesizer's job is to add the variable and its initialization +/// to the ASTs for the expression, and it does so by acting as a SemaConsumer +/// for Clang. //---------------------------------------------------------------------- class ASTResultSynthesizer : public clang::SemaConsumer { public: @@ -68,8 +67,8 @@ public: void Initialize(clang::ASTContext &Context) override; //---------------------------------------------------------------------- - /// Examine a list of Decls to find the function $__lldb_expr and - /// transform its code + /// Examine a list of Decls to find the function $__lldb_expr and transform + /// its code /// /// @param[in] D /// The list of Decls to search. These may contain LinkageSpecDecls, @@ -124,8 +123,8 @@ public: private: //---------------------------------------------------------------------- - /// Hunt the given Decl for FunctionDecls named $__lldb_expr, recursing - /// as necessary through LinkageSpecDecls, and calling SynthesizeResult on + /// Hunt the given Decl for FunctionDecls named $__lldb_expr, recursing as + /// necessary through LinkageSpecDecls, and calling SynthesizeResult on /// anything that was found /// /// @param[in] D @@ -164,8 +163,8 @@ private: bool SynthesizeBodyResult(clang::CompoundStmt *Body, clang::DeclContext *DC); //---------------------------------------------------------------------- - /// Given a DeclContext for a function or method, find all types - /// declared in the context and record any persistent types found. + /// Given a DeclContext for a function or method, find all types declared in + /// the context and record any persistent types found. /// /// @param[in] FunDeclCtx /// The context for the function to process. @@ -173,8 +172,8 @@ private: void RecordPersistentTypes(clang::DeclContext *FunDeclCtx); //---------------------------------------------------------------------- - /// Given a TypeDecl, if it declares a type whose name starts with a - /// dollar sign, register it as a pointer type in the target's scratch + /// Given a TypeDecl, if it declares a type whose name starts with a dollar + /// sign, register it as a pointer type in the target's scratch /// AST context. /// /// @param[in] Body diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ASTStructExtractor.h b/lldb/source/Plugins/ExpressionParser/Clang/ASTStructExtractor.h index 63e3161cae8..65f4b00a865 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ASTStructExtractor.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ASTStructExtractor.h @@ -20,20 +20,19 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ASTStructExtractor ASTStructExtractor.h -/// "lldb/Expression/ASTStructExtractor.h" -/// @brief Extracts and describes the argument structure for a wrapped function. +/// "lldb/Expression/ASTStructExtractor.h" Extracts and describes the argument +/// structure for a wrapped function. /// /// This pass integrates with ClangFunctionCaller, which calls functions with -/// custom -/// sets of arguments. To avoid having to implement the full calling convention -/// for the target's architecture, ClangFunctionCaller writes a simple wrapper -/// function that takes a pointer to an argument structure that contains room -/// for the address of the function to be called, the values of all its -/// arguments, and room for the function's return value. +/// custom sets of arguments. To avoid having to implement the full calling +/// convention for the target's architecture, ClangFunctionCaller writes a +/// simple wrapper function that takes a pointer to an argument structure that +/// contains room for the address of the function to be called, the values of +/// all its arguments, and room for the function's return value. /// -/// The definition of this struct is itself in the body of the wrapper function, -/// so Clang does the structure layout itself. ASTStructExtractor reads through -/// the AST for the wrapper function and finds the struct. +/// The definition of this struct is itself in the body of the wrapper +/// function, so Clang does the structure layout itself. ASTStructExtractor +/// reads through the AST for the wrapper function and finds the struct. //---------------------------------------------------------------------- class ASTStructExtractor : public clang::SemaConsumer { public: @@ -73,8 +72,8 @@ public: void Initialize(clang::ASTContext &Context) override; //---------------------------------------------------------------------- - /// Examine a list of Decls to find the function $__lldb_expr and - /// transform its code + /// Examine a list of Decls to find the function $__lldb_expr and transform + /// its code /// /// @param[in] D /// The list of Decls to search. These may contain LinkageSpecDecls, diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangASTSource.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangASTSource.h index 6f72ad92dc8..a42422b0f97 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangASTSource.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangASTSource.h @@ -25,14 +25,13 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ClangASTSource ClangASTSource.h "lldb/Expression/ClangASTSource.h" -/// @brief Provider for named objects defined in the debug info for Clang +/// Provider for named objects defined in the debug info for Clang /// -/// As Clang parses an expression, it may encounter names that are not -/// defined inside the expression, including variables, functions, and -/// types. Clang knows the name it is looking for, but nothing else. -/// The ExternalSemaSource class provides Decls (VarDecl, FunDecl, TypeDecl) -/// to Clang for these names, consulting the ClangExpressionDeclMap to do -/// the actual lookups. +/// As Clang parses an expression, it may encounter names that are not defined +/// inside the expression, including variables, functions, and types. Clang +/// knows the name it is looking for, but nothing else. The ExternalSemaSource +/// class provides Decls (VarDecl, FunDecl, TypeDecl) to Clang for these +/// names, consulting the ClangExpressionDeclMap to do the actual lookups. //---------------------------------------------------------------------- class ClangASTSource : public ClangExternalASTSourceCommon, public ClangASTImporter::MapCompleter { @@ -78,8 +77,8 @@ public: //------------------------------------------------------------------ /// Look up all Decls that match a particular name. Only handles /// Identifiers and DeclContexts that are either NamespaceDecls or - /// TranslationUnitDecls. Calls SetExternalVisibleDeclsForName with - /// the result. + /// TranslationUnitDecls. Calls SetExternalVisibleDeclsForName with the + /// result. /// /// The work for this function is done by /// void FindExternalVisibleDecls (NameSearchContext &); @@ -173,8 +172,8 @@ public: //------------------------------------------------------------------ /// Called on entering a translation unit. Tells Clang by calling - /// setHasExternalVisibleStorage() and setHasExternalLexicalStorage() - /// that this object has something to say about undefined names. + /// setHasExternalVisibleStorage() and setHasExternalLexicalStorage() that + /// this object has something to say about undefined names. /// /// @param[in] ASTConsumer /// Unused. @@ -186,8 +185,8 @@ public: // //------------------------------------------------------------------ - /// Look up the modules containing a given namespace and put the - /// appropriate entries in the namespace map. + /// Look up the modules containing a given namespace and put the appropriate + /// entries in the namespace map. /// /// @param[in] namespace_map /// The map to be completed. @@ -231,11 +230,10 @@ public: //---------------------------------------------------------------------- /// @class ClangASTSourceProxy ClangASTSource.h - /// "lldb/Expression/ClangASTSource.h" - /// @brief Proxy for ClangASTSource + /// "lldb/Expression/ClangASTSource.h" Proxy for ClangASTSource /// - /// Clang AST contexts like to own their AST sources, so this is a - /// state-free proxy object. + /// Clang AST contexts like to own their AST sources, so this is a state- + /// free proxy object. //---------------------------------------------------------------------- class ClangASTSourceProxy : public ClangExternalASTSourceCommon { public: @@ -298,8 +296,8 @@ public: protected: //------------------------------------------------------------------ - /// Look for the complete version of an Objective-C interface, and - /// return it if found. + /// Look for the complete version of an Objective-C interface, and return it + /// if found. /// /// @param[in] interface_decl /// An ObjCInterfaceDecl that may not be the complete one. @@ -312,8 +310,8 @@ protected: GetCompleteObjCInterface(const clang::ObjCInterfaceDecl *interface_decl); //------------------------------------------------------------------ - /// Find all entities matching a given name in a given module, - /// using a NameSearchContext to make Decls for them. + /// Find all entities matching a given name in a given module, using a + /// NameSearchContext to make Decls for them. /// /// @param[in] context /// The NameSearchContext that can construct Decls for this name. @@ -474,8 +472,9 @@ protected: }; //---------------------------------------------------------------------- -/// @class NameSearchContext ClangASTSource.h "lldb/Expression/ClangASTSource.h" -/// @brief Container for all objects relevant to a single name lookup +/// @class NameSearchContext ClangASTSource.h +/// "lldb/Expression/ClangASTSource.h" Container for all objects relevant to a +/// single name lookup /// /// LLDB needs to create Decls for entities it finds. This class communicates /// what name is being searched for and provides helper functions to construct @@ -532,8 +531,8 @@ struct NameSearchContext { } //------------------------------------------------------------------ - /// Create a VarDecl with the name being searched for and the provided - /// type and register it in the right places. + /// Create a VarDecl with the name being searched for and the provided type + /// and register it in the right places. /// /// @param[in] type /// The opaque QualType for the VarDecl being registered. @@ -541,8 +540,8 @@ struct NameSearchContext { clang::NamedDecl *AddVarDecl(const CompilerType &type); //------------------------------------------------------------------ - /// Create a FunDecl with the name being searched for and the provided - /// type and register it in the right places. + /// Create a FunDecl with the name being searched for and the provided type + /// and register it in the right places. /// /// @param[in] type /// The opaque QualType for the FunDecl being registered. @@ -553,15 +552,14 @@ struct NameSearchContext { clang::NamedDecl *AddFunDecl(const CompilerType &type, bool extern_c = false); //------------------------------------------------------------------ - /// Create a FunDecl with the name being searched for and generic - /// type (i.e. intptr_t NAME_GOES_HERE(...)) and register it in the - /// right places. + /// Create a FunDecl with the name being searched for and generic type (i.e. + /// intptr_t NAME_GOES_HERE(...)) and register it in the right places. //------------------------------------------------------------------ clang::NamedDecl *AddGenericFunDecl(); //------------------------------------------------------------------ - /// Create a TypeDecl with the name being searched for and the provided - /// type and register it in the right places. + /// Create a TypeDecl with the name being searched for and the provided type + /// and register it in the right places. /// /// @param[in] compiler_type /// The opaque QualType for the TypeDecl being registered. @@ -569,8 +567,8 @@ struct NameSearchContext { clang::NamedDecl *AddTypeDecl(const CompilerType &compiler_type); //------------------------------------------------------------------ - /// Add Decls from the provided DeclContextLookupResult to the list - /// of results. + /// Add Decls from the provided DeclContextLookupResult to the list of + /// results. /// /// @param[in] result /// The DeclContextLookupResult, usually returned as the result diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionDeclMap.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionDeclMap.h index d163ad4f7e2..b6738793019 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionDeclMap.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionDeclMap.h @@ -36,29 +36,28 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ClangExpressionDeclMap ClangExpressionDeclMap.h -/// "lldb/Expression/ClangExpressionDeclMap.h" -/// @brief Manages named entities that are defined in LLDB's debug information. +/// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are +/// defined in LLDB's debug information. /// /// The Clang parser uses the ClangASTSource as an interface to request named /// entities from outside an expression. The ClangASTSource reports back, -/// listing -/// all possible objects corresponding to a particular name. But it in turn -/// relies on ClangExpressionDeclMap, which performs several important +/// listing all possible objects corresponding to a particular name. But it +/// in turn relies on ClangExpressionDeclMap, which performs several important /// functions. /// -/// First, it records what variables and functions were looked up and what Decls -/// were returned for them. +/// First, it records what variables and functions were looked up and what +/// Decls were returned for them. /// /// Second, it constructs a struct on behalf of IRForTarget, recording which -/// variables should be placed where and relaying this information back so that -/// IRForTarget can generate context-independent code. +/// variables should be placed where and relaying this information back so +/// that IRForTarget can generate context-independent code. /// /// Third, it "materializes" this struct on behalf of the expression command, /// finding the current values of each variable and placing them into the /// struct so that it can be passed to the JITted version of the IR. /// -/// Fourth and finally, it "dematerializes" the struct after the JITted code has -/// has executed, placing the new values back where it found the old ones. +/// Fourth and finally, it "dematerializes" the struct after the JITted code +/// has has executed, placing the new values back where it found the old ones. //---------------------------------------------------------------------- class ClangExpressionDeclMap : public ClangASTSource { public: @@ -169,8 +168,8 @@ public: lldb::offset_t alignment); //------------------------------------------------------------------ - /// [Used by IRForTarget] Finalize the struct, laying out the position - /// of each object in it. + /// [Used by IRForTarget] Finalize the struct, laying out the position of + /// each object in it. /// /// @return /// True on success; false otherwise. @@ -178,8 +177,8 @@ public: bool DoStructLayout(); //------------------------------------------------------------------ - /// [Used by IRForTarget] Get general information about the laid-out - /// struct after DoStructLayout() has been called. + /// [Used by IRForTarget] Get general information about the laid-out struct + /// after DoStructLayout() has been called. /// /// @param[out] num_elements /// The number of elements in the struct. @@ -197,8 +196,8 @@ public: lldb::offset_t &alignment); //------------------------------------------------------------------ - /// [Used by IRForTarget] Get specific information about one field - /// of the laid-out struct after DoStructLayout() has been called. + /// [Used by IRForTarget] Get specific information about one field of the + /// laid-out struct after DoStructLayout() has been called. /// /// @param[out] decl /// The parsed Decl for the field, as generated by ClangASTSource @@ -232,8 +231,7 @@ public: uint32_t index); //------------------------------------------------------------------ - /// [Used by IRForTarget] Get information about a function given its - /// Decl. + /// [Used by IRForTarget] Get information about a function given its Decl. /// /// @param[in] decl /// The parsed Decl for the Function, as generated by ClangASTSource @@ -248,8 +246,8 @@ public: bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr); //------------------------------------------------------------------ - /// [Used by IRForTarget] Get the address of a symbol given nothing - /// but its name. + /// [Used by IRForTarget] Get the address of a symbol given nothing but its + /// name. /// /// @param[in] target /// The target to find the symbol in. If not provided, @@ -303,8 +301,8 @@ public: TargetInfo GetTargetInfo(); //------------------------------------------------------------------ - /// [Used by ClangASTSource] Find all entities matching a given name, - /// using a NameSearchContext to make Decls for them. + /// [Used by ClangASTSource] Find all entities matching a given name, using + /// a NameSearchContext to make Decls for them. /// /// @param[in] context /// The NameSearchContext that can construct Decls for this name. @@ -442,14 +440,13 @@ private: void DisableStructVars() { m_struct_vars.reset(); } //---------------------------------------------------------------------- - /// Get this parser's ID for use in extracting parser- and JIT-specific - /// data from persistent variables. + /// Get this parser's ID for use in extracting parser- and JIT-specific data + /// from persistent variables. //---------------------------------------------------------------------- uint64_t GetParserID() { return (uint64_t) this; } //------------------------------------------------------------------ - /// Given a target, find a variable that matches the given name and - /// type. + /// Given a target, find a variable that matches the given name and type. /// /// @param[in] target /// The target to use as a basis for finding the variable. @@ -477,8 +474,8 @@ private: TypeFromUser *type = NULL); //------------------------------------------------------------------ - /// Get the value of a variable in a given execution context and return - /// the associated Types if needed. + /// Get the value of a variable in a given execution context and return the + /// associated Types if needed. /// /// @param[in] var /// The variable to evaluate. @@ -524,8 +521,8 @@ private: lldb::ValueObjectSP valobj, unsigned int current_id); //------------------------------------------------------------------ - /// Use the NameSearchContext to generate a Decl for the given - /// persistent variable, and put it in the list of found entities. + /// Use the NameSearchContext to generate a Decl for the given persistent + /// variable, and put it in the list of found entities. /// /// @param[in] context /// The NameSearchContext to use when constructing the Decl. @@ -542,9 +539,8 @@ private: unsigned int current_id); //------------------------------------------------------------------ - /// Use the NameSearchContext to generate a Decl for the given LLDB - /// symbol (treated as a variable), and put it in the list of found - /// entities. + /// Use the NameSearchContext to generate a Decl for the given LLDB symbol + /// (treated as a variable), and put it in the list of found entities. /// /// @param[in] context /// The NameSearchContext to use when constructing the Decl. @@ -556,9 +552,9 @@ private: unsigned int current_id); //------------------------------------------------------------------ - /// Use the NameSearchContext to generate a Decl for the given - /// function. (Functions are not placed in the Tuple list.) Can - /// handle both fully typed functions and generic functions. + /// Use the NameSearchContext to generate a Decl for the given function. + /// (Functions are not placed in the Tuple list.) Can handle both fully + /// typed functions and generic functions. /// /// @param[in] context /// The NameSearchContext to use when constructing the Decl. @@ -575,8 +571,7 @@ private: unsigned int current_id); //------------------------------------------------------------------ - /// Use the NameSearchContext to generate a Decl for the given - /// register. + /// Use the NameSearchContext to generate a Decl for the given register. /// /// @param[in] context /// The NameSearchContext to use when constructing the Decl. @@ -588,8 +583,8 @@ private: unsigned int current_id); //------------------------------------------------------------------ - /// Use the NameSearchContext to generate a Decl for the given - /// type. (Types are not placed in the Tuple list.) + /// Use the NameSearchContext to generate a Decl for the given type. (Types + /// are not placed in the Tuple list.) /// /// @param[in] context /// The NameSearchContext to use when constructing the Decl. @@ -601,8 +596,8 @@ private: unsigned int current_id); //------------------------------------------------------------------ - /// Generate a Decl for "*this" and add a member function declaration - /// to it for the expression, then report it. + /// Generate a Decl for "*this" and add a member function declaration to it + /// for the expression, then report it. /// /// @param[in] context /// The NameSearchContext to use when constructing the Decl. diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionParser.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionParser.h index 41f290f2e12..4058ec1270b 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionParser.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionParser.h @@ -26,14 +26,14 @@ class IRExecutionUnit; //---------------------------------------------------------------------- /// @class ClangExpressionParser ClangExpressionParser.h -/// "lldb/Expression/ClangExpressionParser.h" -/// @brief Encapsulates an instance of Clang that can parse expressions. +/// "lldb/Expression/ClangExpressionParser.h" Encapsulates an instance of +/// Clang that can parse expressions. /// /// ClangExpressionParser is responsible for preparing an instance of /// ClangExpression for execution. ClangExpressionParser uses ClangExpression /// as a glorified parameter list, performing the required parsing and -/// conversion to formats (DWARF bytecode, or JIT compiled machine code) -/// that can be executed. +/// conversion to formats (DWARF bytecode, or JIT compiled machine code) that +/// can be executed. //---------------------------------------------------------------------- class ClangExpressionParser : public ExpressionParser { public: @@ -59,8 +59,8 @@ public: ~ClangExpressionParser() override; //------------------------------------------------------------------ - /// Parse a single expression and convert it to IR using Clang. Don't - /// wrap the expression in anything at all. + /// Parse a single expression and convert it to IR using Clang. Don't wrap + /// the expression in anything at all. /// /// @param[in] diagnostic_manager /// The diagnostic manager to report errors to. @@ -74,8 +74,8 @@ public: bool RewriteExpression(DiagnosticManager &diagnostic_manager) override; //------------------------------------------------------------------ - /// Ready an already-parsed expression for execution, possibly - /// evaluating it statically. + /// Ready an already-parsed expression for execution, possibly evaluating it + /// statically. /// /// @param[out] func_addr /// The address to which the function has been written. diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionVariable.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionVariable.h index baa80d7ba0d..7d5ced5b470 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionVariable.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionVariable.h @@ -41,27 +41,25 @@ class ValueObjectConstResult; //---------------------------------------------------------------------- /// @class ClangExpressionVariable ClangExpressionVariable.h -/// "lldb/Expression/ClangExpressionVariable.h" -/// @brief Encapsulates one variable for the expression parser. +/// "lldb/Expression/ClangExpressionVariable.h" Encapsulates one variable for +/// the expression parser. /// /// The expression parser uses variables in three different contexts: /// -/// First, it stores persistent variables along with the process for use -/// in expressions. These persistent variables contain their own data -/// and are typed. +/// First, it stores persistent variables along with the process for use in +/// expressions. These persistent variables contain their own data and are +/// typed. /// -/// Second, in an interpreted expression, it stores the local variables -/// for the expression along with the expression. These variables -/// contain their own data and are typed. +/// Second, in an interpreted expression, it stores the local variables for +/// the expression along with the expression. These variables contain their +/// own data and are typed. /// -/// Third, in a JIT-compiled expression, it stores the variables that -/// the expression needs to have materialized and dematerialized at each -/// execution. These do not contain their own data but are named and -/// typed. +/// Third, in a JIT-compiled expression, it stores the variables that the +/// expression needs to have materialized and dematerialized at each +/// execution. These do not contain their own data but are named and typed. /// -/// This class supports all of these use cases using simple type -/// polymorphism, and provides necessary support methods. Its interface -/// is RTTI-neutral. +/// This class supports all of these use cases using simple type polymorphism, +/// and provides necessary support methods. Its interface is RTTI-neutral. //---------------------------------------------------------------------- class ClangExpressionVariable : public ExpressionVariable { public: @@ -79,8 +77,8 @@ public: lldb::ByteOrder byte_order, uint32_t addr_byte_size); //---------------------------------------------------------------------- - /// Utility functions for dealing with ExpressionVariableLists in - /// Clang-specific ways + /// Utility functions for dealing with ExpressionVariableLists in Clang- + /// specific ways //---------------------------------------------------------------------- //---------------------------------------------------------------------- @@ -112,9 +110,9 @@ public: } //---------------------------------------------------------------------- - /// If the variable contains its own data, make a Value point at it. - /// If \a exe_ctx in not NULL, the value will be resolved in with - /// that execution context. + /// If the variable contains its own data, make a Value point at it. If \a + /// exe_ctx in not NULL, the value will be resolved in with that execution + /// context. /// /// @param[in] value /// The value to point at the data. @@ -156,8 +154,8 @@ private: public: //---------------------------------------------------------------------- - /// Make this variable usable by the parser by allocating space for - /// parser-specific variables + /// Make this variable usable by the parser by allocating space for parser- + /// specific variables //---------------------------------------------------------------------- void EnableParserVars(uint64_t parser_id) { m_parser_vars.insert(std::make_pair(parser_id, ParserVars())); diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangFunctionCaller.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangFunctionCaller.h index 0596d8fde7b..438cf0c713d 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangFunctionCaller.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangFunctionCaller.h @@ -31,8 +31,8 @@ class ClangExpressionParser; //---------------------------------------------------------------------- /// @class ClangFunctionCaller ClangFunctionCaller.h -/// "lldb/Expression/ClangFunctionCaller.h" -/// @brief Encapsulates a function that can be called. +/// "lldb/Expression/ClangFunctionCaller.h" Encapsulates a function that can +/// be called. /// /// A given ClangFunctionCaller object can handle a single function signature. /// Once constructed, it can set up any number of concurrent calls to @@ -56,8 +56,8 @@ class ClangExpressionParser; /// If you need to call the function on the thread plan stack, you can also /// call InsertFunction() followed by GetThreadPlanToCallFunction(). /// -/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed -/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated +/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed a +/// pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated /// and its address returned in that variable. /// /// Any of the methods that take arg_addr_ptr can be passed NULL, and the @@ -79,8 +79,8 @@ class ClangFunctionCaller : public FunctionCaller { ClangExpressionDeclMap *DeclMap() override { return NULL; } //------------------------------------------------------------------ - /// Return the object that the parser should allow to access ASTs. - /// May be NULL if the ASTs do not need to be transformed. + /// Return the object that the parser should allow to access ASTs. May be + /// NULL if the ASTs do not need to be transformed. /// /// @param[in] passthrough /// The ASTConsumer that the returned transformer should send diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangPersistentVariables.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangPersistentVariables.h index 1432fae711e..59126974616 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangPersistentVariables.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangPersistentVariables.h @@ -25,9 +25,8 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ClangPersistentVariables ClangPersistentVariables.h -/// "lldb/Expression/ClangPersistentVariables.h" -/// @brief Manages persistent values that need to be preserved between -/// expression invocations. +/// "lldb/Expression/ClangPersistentVariables.h" Manages persistent values +/// that need to be preserved between expression invocations. /// /// A list of variables that can be accessed and updated by any expression. See /// ClangPersistentVariable for more discussion. Also provides an increasing, diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangUserExpression.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangUserExpression.h index 16d4af8b167..434168e2ce5 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangUserExpression.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangUserExpression.h @@ -35,13 +35,13 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ClangUserExpression ClangUserExpression.h -/// "lldb/Expression/ClangUserExpression.h" -/// @brief Encapsulates a single expression for use with Clang +/// "lldb/Expression/ClangUserExpression.h" Encapsulates a single expression +/// for use with Clang /// /// LLDB uses expressions for various purposes, notably to call functions /// and as a backend for the expr command. ClangUserExpression encapsulates -/// the objects needed to parse and interpret or JIT an expression. It -/// uses the Clang parser to produce LLVM IR from the expression. +/// the objects needed to parse and interpret or JIT an expression. It uses +/// the Clang parser to produce LLVM IR from the expression. //---------------------------------------------------------------------- class ClangUserExpression : public LLVMUserExpression { public: @@ -69,8 +69,8 @@ public: bool keep_result_in_memory); //------------------------------------------------------------------ - /// Return the object that the parser should allow to access ASTs. - /// May be NULL if the ASTs do not need to be transformed. + /// Return the object that the parser should allow to access ASTs. May be + /// NULL if the ASTs do not need to be transformed. /// /// @param[in] passthrough /// The ASTConsumer that the returned transformer should send diff --git a/lldb/source/Plugins/ExpressionParser/Clang/ClangUtilityFunction.h b/lldb/source/Plugins/ExpressionParser/Clang/ClangUtilityFunction.h index 80577199b81..a897a2b1708 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/ClangUtilityFunction.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/ClangUtilityFunction.h @@ -29,15 +29,15 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class ClangUtilityFunction ClangUtilityFunction.h -/// "lldb/Expression/ClangUtilityFunction.h" -/// @brief Encapsulates a single expression for use with Clang +/// "lldb/Expression/ClangUtilityFunction.h" Encapsulates a single expression +/// for use with Clang /// /// LLDB uses expressions for various purposes, notably to call functions /// and as a backend for the expr command. ClangUtilityFunction encapsulates /// a self-contained function meant to be used from other code. Utility /// functions can perform error-checking for ClangUserExpressions, or can -/// simply provide a way to push a function into the target for the debugger to -/// call later on. +/// simply provide a way to push a function into the target for the debugger +/// to call later on. //---------------------------------------------------------------------- class ClangUtilityFunction : public UtilityFunction { public: @@ -60,8 +60,8 @@ public: void ResetDeclMap(ExecutionContext &exe_ctx, bool keep_result_in_memory); //------------------------------------------------------------------ - /// Return the object that the parser should allow to access ASTs. - /// May be NULL if the ASTs do not need to be transformed. + /// Return the object that the parser should allow to access ASTs. May be + /// NULL if the ASTs do not need to be transformed. /// /// @param[in] passthrough /// The ASTConsumer that the returned transformer should send diff --git a/lldb/source/Plugins/ExpressionParser/Clang/IRForTarget.h b/lldb/source/Plugins/ExpressionParser/Clang/IRForTarget.h index 93ce8aa44eb..c6c44b46023 100644 --- a/lldb/source/Plugins/ExpressionParser/Clang/IRForTarget.h +++ b/lldb/source/Plugins/ExpressionParser/Clang/IRForTarget.h @@ -47,12 +47,11 @@ class IRMemoryMap; //---------------------------------------------------------------------- /// @class IRForTarget IRForTarget.h "lldb/Expression/IRForTarget.h" -/// @brief Transforms the IR for a function to run in the target +/// Transforms the IR for a function to run in the target /// -/// Once an expression has been parsed and converted to IR, it can run -/// in two contexts: interpreted by LLDB as a DWARF location expression, -/// or compiled by the JIT and inserted into the target process for -/// execution. +/// Once an expression has been parsed and converted to IR, it can run in two +/// contexts: interpreted by LLDB as a DWARF location expression, or compiled +/// by the JIT and inserted into the target process for execution. /// /// IRForTarget makes the second possible, by applying a series of /// transformations to the IR which make it relocatable. These @@ -126,8 +125,7 @@ public: //------------------------------------------------------------------ /// Interface stub /// - /// Implementation of the llvm::ModulePass::assignPassManager() - /// function. + /// Implementation of the llvm::ModulePass::assignPassManager() function. //------------------------------------------------------------------ void assignPassManager(llvm::PMStack &pass_mgr_stack, llvm::PassManagerType pass_mgr_type = @@ -179,8 +177,8 @@ private: //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Get the address of a function, and a location to put the complete - /// Value of the function if one is available. + /// Get the address of a function, and a location to put the complete Value + /// of the function if one is available. /// /// @param[in] function /// The function to find the location of. @@ -204,13 +202,13 @@ private: //------------------------------------------------------------------ /// A function-level pass to take the generated global value - /// $__lldb_expr_result and make it into a persistent variable. - /// Also see ASTResultSynthesizer. + /// $__lldb_expr_result and make it into a persistent variable. Also see + /// ASTResultSynthesizer. //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Find the NamedDecl corresponding to a Value. This interface is - /// exposed for the IR interpreter. + /// Find the NamedDecl corresponding to a Value. This interface is exposed + /// for the IR interpreter. /// /// @param[in] module /// The module containing metadata to search @@ -230,8 +228,8 @@ private: //------------------------------------------------------------------ /// Set the constant result variable m_const_result to the provided - /// constant, assuming it can be evaluated. The result variable - /// will be reset to NULL later if the expression has side effects. + /// constant, assuming it can be evaluated. The result variable will be + /// reset to NULL later if the expression has side effects. /// /// @param[in] initializer /// The constant initializer for the variable. @@ -247,8 +245,8 @@ private: lldb_private::TypeFromParser type); //------------------------------------------------------------------ - /// If the IR represents a cast of a variable, set m_const_result - /// to the result of the cast. The result variable will be reset to + /// If the IR represents a cast of a variable, set m_const_result to the + /// result of the cast. The result variable will be reset to /// NULL latger if the expression has side effects. /// /// @param[in] type @@ -301,10 +299,9 @@ private: /// rewrite them to use sel_registerName instead of statically allocated /// selectors. The reason is that the selectors are created on the /// assumption that the Objective-C runtime will scan the appropriate - /// section and prepare them. This doesn't happen when code is copied - /// into the target, though, and there's no easy way to induce the - /// runtime to scan them. So instead we get our selectors from - /// sel_registerName. + /// section and prepare them. This doesn't happen when code is copied into + /// the target, though, and there's no easy way to induce the runtime to + /// scan them. So instead we get our selectors from sel_registerName. //------------------------------------------------------------------ //------------------------------------------------------------------ @@ -359,13 +356,12 @@ private: //------------------------------------------------------------------ /// A basic block-level pass to find all newly-declared persistent - /// variables and register them with the ClangExprDeclMap. This - /// allows them to be materialized and dematerialized like normal - /// external variables. Before transformation, these persistent - /// variables look like normal locals, so they have an allocation. - /// This pass excises these allocations and makes references look - /// like external references where they will be resolved -- like all - /// other external references -- by ResolveExternals(). + /// variables and register them with the ClangExprDeclMap. This allows them + /// to be materialized and dematerialized like normal external variables. + /// Before transformation, these persistent variables look like normal + /// locals, so they have an allocation. This pass excises these allocations + /// and makes references look like external references where they will be + /// resolved -- like all other external references -- by ResolveExternals(). //------------------------------------------------------------------ //------------------------------------------------------------------ @@ -389,15 +385,14 @@ private: //------------------------------------------------------------------ /// A function-level pass to find all external variables and functions - /// used in the IR. Each found external variable is added to the - /// struct, and each external function is resolved in place, its call - /// replaced with a call to a function pointer whose value is the - /// address of the function in the target process. + /// used in the IR. Each found external variable is added to the struct, + /// and each external function is resolved in place, its call replaced with + /// a call to a function pointer whose value is the address of the function + /// in the target process. //------------------------------------------------------------------ //------------------------------------------------------------------ - /// Write an initializer to a memory array of assumed sufficient - /// size. + /// Write an initializer to a memory array of assumed sufficient size. /// /// @param[in] data /// A pointer to the data to write to. @@ -504,8 +499,8 @@ private: //------------------------------------------------------------------ /// A basic block-level pass to excise guard variables from the code. /// The result for the function is passed through Clang as a static - /// variable. Static variables normally have guard variables to - /// ensure that they are only initialized once. + /// variable. Static variables normally have guard variables to ensure that + /// they are only initialized once. //------------------------------------------------------------------ //------------------------------------------------------------------ @@ -529,9 +524,9 @@ private: //------------------------------------------------------------------ /// A function-level pass to make all external variable references - /// point at the correct offsets from the void* passed into the - /// function. ClangExpressionDeclMap::DoStructLayout() must be called - /// beforehand, so that the offsets are valid. + /// point at the correct offsets from the void* passed into the function. + /// ClangExpressionDeclMap::DoStructLayout() must be called beforehand, so + /// that the offsets are valid. //------------------------------------------------------------------ //------------------------------------------------------------------ @@ -583,7 +578,8 @@ private: llvm::StoreInst *m_result_store; ///< If non-NULL, the store instruction that ///writes to the result variable. If - /// m_has_side_effects is true, this is NULL. + /// m_has_side_effects is true, this is + /// NULL. bool m_result_is_pointer; ///< True if the function's result in the AST is a ///pointer (see comments in /// ASTResultSynthesizer::SynthesizeBodyResult) @@ -594,18 +590,17 @@ private: /// location of the static allocation. //------------------------------------------------------------------ - /// UnfoldConstant operates on a constant [Old] which has just been - /// replaced with a value [New]. We assume that new_value has - /// been properly placed early in the function, in front of the - /// first instruction in the entry basic block - /// [FirstEntryInstruction]. + /// UnfoldConstant operates on a constant [Old] which has just been replaced + /// with a value [New]. We assume that new_value has been properly placed + /// early in the function, in front of the first instruction in the entry + /// basic block [FirstEntryInstruction]. /// - /// UnfoldConstant reads through the uses of Old and replaces Old - /// in those uses with New. Where those uses are constants, the - /// function generates new instructions to compute the result of the - /// new, non-constant expression and places them before - /// FirstEntryInstruction. These instructions replace the constant - /// uses, so UnfoldConstant calls itself recursively for those. + /// UnfoldConstant reads through the uses of Old and replaces Old in those + /// uses with New. Where those uses are constants, the function generates + /// new instructions to compute the result of the new, non-constant + /// expression and places them before FirstEntryInstruction. These + /// instructions replace the constant uses, so UnfoldConstant calls itself + /// recursively for those. /// /// @param[in] llvm_function /// The function currently being processed. @@ -637,8 +632,8 @@ private: lldb_private::Stream &error_stream); //------------------------------------------------------------------ - /// Construct a reference to m_reloc_placeholder with a given type - /// and offset. This typically happens after inserting data into + /// Construct a reference to m_reloc_placeholder with a given type and + /// offset. This typically happens after inserting data into /// m_data_allocator. /// /// @param[in] type @@ -653,8 +648,8 @@ private: llvm::Constant *BuildRelocation(llvm::Type *type, uint64_t offset); //------------------------------------------------------------------ - /// Commit the allocation in m_data_allocator and use its final - /// location to replace m_reloc_placeholder. + /// Commit the allocation in m_data_allocator and use its final location to + /// replace m_reloc_placeholder. /// /// @param[in] module /// The module that m_data_allocator resides in diff --git a/lldb/source/Plugins/ExpressionParser/Go/GoUserExpression.h b/lldb/source/Plugins/ExpressionParser/Go/GoUserExpression.h index 5d55b296ed3..e2839da9bfd 100644 --- a/lldb/source/Plugins/ExpressionParser/Go/GoUserExpression.h +++ b/lldb/source/Plugins/ExpressionParser/Go/GoUserExpression.h @@ -50,12 +50,12 @@ private: //---------------------------------------------------------------------- /// @class GoUserExpression GoUserExpression.h -/// "lldb/Expression/GoUserExpression.h" -/// @brief Encapsulates a single expression for use with Go +/// "lldb/Expression/GoUserExpression.h" Encapsulates a single expression for +/// use with Go /// /// LLDB uses expressions for various purposes, notably to call functions -/// and as a backend for the expr command. GoUserExpression encapsulates -/// the objects needed to parse and interpret an expression. +/// and as a backend for the expr command. GoUserExpression encapsulates the +/// objects needed to parse and interpret an expression. //---------------------------------------------------------------------- class GoUserExpression : public UserExpression { public: diff --git a/lldb/source/Plugins/ObjectFile/ELF/ELFHeader.h b/lldb/source/Plugins/ObjectFile/ELF/ELFHeader.h index 4e2d3155ebb..faaf8be99d6 100644 --- a/lldb/source/Plugins/ObjectFile/ELF/ELFHeader.h +++ b/lldb/source/Plugins/ObjectFile/ELF/ELFHeader.h @@ -8,14 +8,14 @@ //===----------------------------------------------------------------------===// // /// @file -/// @brief Generic structures and typedefs for ELF files. +/// Generic structures and typedefs for ELF files. /// /// This file provides definitions for the various entities comprising an ELF /// file. The structures are generic in the sense that they do not correspond /// to the exact binary layout of an ELF, but can be used to hold the /// information present in both 32 and 64 bit variants of the format. Each -/// entity provides a \c Parse method which is capable of transparently reading -/// both 32 and 64 bit instances of the object. +/// entity provides a \c Parse method which is capable of transparently +/// reading both 32 and 64 bit instances of the object. //===----------------------------------------------------------------------===// #ifndef liblldb_ELFHeader_h_ @@ -35,8 +35,9 @@ namespace elf { //------------------------------------------------------------------------------ /// @name ELF type definitions. /// -/// Types used to represent the various components of ELF structures. All types -/// are signed or unsigned integral types wide enough to hold values from both +/// Types used to represent the various components of ELF structures. All +/// types are signed or unsigned integral types wide enough to hold values +/// from both /// 32 and 64 bit ELF variants. //@{ typedef uint64_t elf_addr; @@ -51,10 +52,10 @@ typedef int64_t elf_sxword; //------------------------------------------------------------------------------ /// @class ELFHeader -/// @brief Generic representation of an ELF file header. +/// Generic representation of an ELF file header. /// -/// This object is used to identify the general attributes on an ELF file and to -/// locate additional sections within the file. +/// This object is used to identify the general attributes on an ELF file and +/// to locate additional sections within the file. struct ELFHeader { unsigned char e_ident[llvm::ELF::EI_NIDENT]; ///< ELF file identification. elf_addr e_entry; ///< Virtual address program entry point. @@ -118,9 +119,9 @@ struct ELFHeader { bool HasHeaderExtension() const; //-------------------------------------------------------------------------- - /// Parse an ELFHeader entry starting at position \p offset and - /// update the data extractor with the address size and byte order - /// attributes as defined by the header. + /// Parse an ELFHeader entry starting at position \p offset and update the + /// data extractor with the address size and byte order attributes as + /// defined by the header. /// /// @param[in,out] data /// The DataExtractor to read from. Updated with the address size and @@ -157,8 +158,8 @@ struct ELFHeader { private: //-------------------------------------------------------------------------- - /// Parse an ELFHeader header extension entry. This method is called - /// by Parse(). + /// Parse an ELFHeader header extension entry. This method is called by + /// Parse(). /// /// @param[in] data /// The DataExtractor to read from. @@ -167,7 +168,7 @@ private: //------------------------------------------------------------------------------ /// @class ELFSectionHeader -/// @brief Generic representation of an ELF section header. +/// Generic representation of an ELF section header. struct ELFSectionHeader { elf_word sh_name; ///< Section name string index. elf_word sh_type; ///< Section type. @@ -202,7 +203,7 @@ struct ELFSectionHeader { //------------------------------------------------------------------------------ /// @class ELFProgramHeader -/// @brief Generic representation of an ELF program header. +/// Generic representation of an ELF program header. struct ELFProgramHeader { elf_word p_type; ///< Type of program segment. elf_word p_flags; ///< Segment attributes. @@ -235,7 +236,7 @@ struct ELFProgramHeader { //------------------------------------------------------------------------------ /// @class ELFSymbol -/// @brief Represents a symbol within an ELF symbol table. +/// Represents a symbol within an ELF symbol table. struct ELFSymbol { elf_addr st_value; ///< Absolute or relocatable address. elf_xword st_size; ///< Size of the symbol or zero. @@ -288,7 +289,7 @@ struct ELFSymbol { //------------------------------------------------------------------------------ /// @class ELFDynamic -/// @brief Represents an entry in an ELF dynamic table. +/// Represents an entry in an ELF dynamic table. struct ELFDynamic { elf_sxword d_tag; ///< Type of dynamic table entry. union { @@ -318,7 +319,7 @@ struct ELFDynamic { //------------------------------------------------------------------------------ /// @class ELFRel -/// @brief Represents a relocation entry with an implicit addend. +/// Represents a relocation entry with an implicit addend. struct ELFRel { elf_addr r_offset; ///< Address of reference. elf_xword r_info; ///< symbol index and type of relocation. @@ -360,7 +361,7 @@ struct ELFRel { //------------------------------------------------------------------------------ /// @class ELFRela -/// @brief Represents a relocation entry with an explicit addend. +/// Represents a relocation entry with an explicit addend. struct ELFRela { elf_addr r_offset; ///< Address of reference. elf_xword r_info; ///< Symbol index and type of relocation. diff --git a/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp b/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp index 923a74935a7..3fbcaa28a91 100644 --- a/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp +++ b/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.cpp @@ -113,7 +113,7 @@ const elf_word LLDB_NT_GNU_ABI_OS_SOLARIS = 0x02; //===----------------------------------------------------------------------===// /// @class ELFRelocation -/// @brief Generic wrapper for ELFRel and ELFRela. +/// Generic wrapper for ELFRel and ELFRela. /// /// This helper class allows us to parse both ELFRel and ELFRela relocation /// entries in a generic manner. diff --git a/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h b/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h index 7b2a379f392..e84c8038b19 100644 --- a/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h +++ b/lldb/source/Plugins/ObjectFile/ELF/ObjectFileELF.h @@ -54,10 +54,10 @@ struct ELFNote { //------------------------------------------------------------------------------ /// @class ObjectFileELF -/// @brief Generic ELF object file reader. +/// Generic ELF object file reader. /// -/// This class provides a generic ELF (32/64 bit) reader plugin implementing the -/// ObjectFile protocol. +/// This class provides a generic ELF (32/64 bit) reader plugin implementing +/// the ObjectFile protocol. class ObjectFileELF : public lldb_private::ObjectFile { public: ~ObjectFileELF() override; @@ -260,8 +260,8 @@ private: uint64_t length, lldb_private::ArchSpec &arch_spec); - /// Parses the elf section headers and returns the uuid, debug link name, crc, - /// archspec. + /// Parses the elf section headers and returns the uuid, debug link name, + /// crc, archspec. static size_t GetSectionHeaderInfo(SectionHeaderColl §ion_headers, lldb_private::DataExtractor &object_data, const elf::ELFHeader &header, diff --git a/lldb/source/Plugins/Process/Darwin/NativeProcessDarwin.h b/lldb/source/Plugins/Process/Darwin/NativeProcessDarwin.h index 649280c17a8..0b186fd7d80 100644 --- a/lldb/source/Plugins/Process/Darwin/NativeProcessDarwin.h +++ b/lldb/source/Plugins/Process/Darwin/NativeProcessDarwin.h @@ -43,10 +43,10 @@ class Scalar; namespace process_darwin { /// @class NativeProcessDarwin -/// @brief Manages communication with the inferior (debugee) process. +/// Manages communication with the inferior (debugee) process. /// -/// Upon construction, this class prepares and launches an inferior -/// process for debugging. +/// Upon construction, this class prepares and launches an inferior process +/// for debugging. /// /// Changes in the inferior process state are broadcasted. class NativeProcessDarwin : public NativeProcessProtocol { @@ -205,10 +205,10 @@ private: // ----------------------------------------------------------------- /// Finalize the launch. /// - /// This method associates the NativeProcessDarwin instance with - /// the host process that was just launched. It peforms actions - /// like attaching a listener to the inferior exception port, - /// ptracing the process, and the like. + /// This method associates the NativeProcessDarwin instance with the host + /// process that was just launched. It peforms actions like attaching a + /// listener to the inferior exception port, ptracing the process, and the + /// like. /// /// @param[in] launch_flavor /// The launch flavor that was used to launch the process. @@ -263,8 +263,8 @@ private: task_t TaskPortForProcessID(Status &error, bool force = false) const; - /// Attaches to an existing process. Forms the - /// implementation of Process::DoAttach. + /// Attaches to an existing process. Forms the implementation of + /// Process::DoAttach. void AttachToInferior(MainLoop &mainloop, lldb::pid_t pid, Status &error); ::pid_t Attach(lldb::pid_t pid, Status &error); @@ -323,8 +323,8 @@ private: Status GetSignalInfo(lldb::tid_t tid, void *siginfo); /// Writes the raw event message code (vis-a-vis PTRACE_GETEVENTMSG) - /// corresponding to the given thread ID to the memory pointed to - /// by @p message. + /// corresponding to the given thread ID to the memory pointed to by @p + /// message. Status GetEventMessage(lldb::tid_t tid, unsigned long *message); void NotifyThreadDeath(lldb::tid_t tid); diff --git a/lldb/source/Plugins/Process/FreeBSD/FreeBSDThread.h b/lldb/source/Plugins/Process/FreeBSD/FreeBSDThread.h index 72e84645955..c93cc4fbfd7 100644 --- a/lldb/source/Plugins/Process/FreeBSD/FreeBSDThread.h +++ b/lldb/source/Plugins/Process/FreeBSD/FreeBSDThread.h @@ -24,7 +24,7 @@ class POSIXBreakpointProtocol; //------------------------------------------------------------------------------ // @class FreeBSDThread -// @brief Abstraction of a FreeBSD thread. +// Abstraction of a FreeBSD thread. class FreeBSDThread : public lldb_private::Thread { public: //------------------------------------------------------------------ diff --git a/lldb/source/Plugins/Process/FreeBSD/POSIXStopInfo.h b/lldb/source/Plugins/Process/FreeBSD/POSIXStopInfo.h index 96861852b38..ff369310717 100644 --- a/lldb/source/Plugins/Process/FreeBSD/POSIXStopInfo.h +++ b/lldb/source/Plugins/Process/FreeBSD/POSIXStopInfo.h @@ -17,7 +17,7 @@ //===----------------------------------------------------------------------===// /// @class POSIXStopInfo -/// @brief Simple base class for all POSIX-specific StopInfo objects. +/// Simple base class for all POSIX-specific StopInfo objects. /// class POSIXStopInfo : public lldb_private::StopInfo { public: @@ -27,7 +27,7 @@ public: //===----------------------------------------------------------------------===// /// @class POSIXLimboStopInfo -/// @brief Represents the stop state of a process ready to exit. +/// Represents the stop state of a process ready to exit. /// class POSIXLimboStopInfo : public POSIXStopInfo { public: @@ -46,7 +46,7 @@ public: //===----------------------------------------------------------------------===// /// @class POSIXNewThreadStopInfo -/// @brief Represents the stop state of process when a new thread is spawned. +/// Represents the stop state of process when a new thread is spawned. /// class POSIXNewThreadStopInfo : public POSIXStopInfo { diff --git a/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.cpp b/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.cpp index a498e559915..51fdf2e5ef3 100644 --- a/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.cpp +++ b/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.cpp @@ -201,15 +201,16 @@ static bool EnsureFDFlags(int fd, int flags, Status &error) { //------------------------------------------------------------------------------ /// @class Operation -/// @brief Represents a ProcessMonitor operation. +/// Represents a ProcessMonitor operation. /// -/// Under FreeBSD, it is not possible to ptrace() from any other thread but the -/// one that spawned or attached to the process from the start. Therefore, when -/// a ProcessMonitor is asked to deliver or change the state of an inferior -/// process the operation must be "funneled" to a specific thread to perform the -/// task. The Operation class provides an abstract base for all services the -/// ProcessMonitor must perform via the single virtual function Execute, thus -/// encapsulating the code that needs to run in the privileged context. +/// Under FreeBSD, it is not possible to ptrace() from any other thread but +/// the one that spawned or attached to the process from the start. +/// Therefore, when a ProcessMonitor is asked to deliver or change the state +/// of an inferior process the operation must be "funneled" to a specific +/// thread to perform the task. The Operation class provides an abstract base +/// for all services the ProcessMonitor must perform via the single virtual +/// function Execute, thus encapsulating the code that needs to run in the +/// privileged context. class Operation { public: virtual ~Operation() {} @@ -218,7 +219,7 @@ public: //------------------------------------------------------------------------------ /// @class ReadOperation -/// @brief Implements ProcessMonitor::ReadMemory. +/// Implements ProcessMonitor::ReadMemory. class ReadOperation : public Operation { public: ReadOperation(lldb::addr_t addr, void *buff, size_t size, Status &error, @@ -244,7 +245,7 @@ void ReadOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class WriteOperation -/// @brief Implements ProcessMonitor::WriteMemory. +/// Implements ProcessMonitor::WriteMemory. class WriteOperation : public Operation { public: WriteOperation(lldb::addr_t addr, const void *buff, size_t size, @@ -270,7 +271,7 @@ void WriteOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class ReadRegOperation -/// @brief Implements ProcessMonitor::ReadRegisterValue. +/// Implements ProcessMonitor::ReadRegisterValue. class ReadRegOperation : public Operation { public: ReadRegOperation(lldb::tid_t tid, unsigned offset, unsigned size, @@ -310,7 +311,7 @@ void ReadRegOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class WriteRegOperation -/// @brief Implements ProcessMonitor::WriteRegisterValue. +/// Implements ProcessMonitor::WriteRegisterValue. class WriteRegOperation : public Operation { public: WriteRegOperation(lldb::tid_t tid, unsigned offset, @@ -343,7 +344,7 @@ void WriteRegOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class ReadDebugRegOperation -/// @brief Implements ProcessMonitor::ReadDebugRegisterValue. +/// Implements ProcessMonitor::ReadDebugRegisterValue. class ReadDebugRegOperation : public Operation { public: ReadDebugRegOperation(lldb::tid_t tid, unsigned offset, unsigned size, @@ -378,7 +379,7 @@ void ReadDebugRegOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class WriteDebugRegOperation -/// @brief Implements ProcessMonitor::WriteDebugRegisterValue. +/// Implements ProcessMonitor::WriteDebugRegisterValue. class WriteDebugRegOperation : public Operation { public: WriteDebugRegOperation(lldb::tid_t tid, unsigned offset, @@ -411,7 +412,7 @@ void WriteDebugRegOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class ReadGPROperation -/// @brief Implements ProcessMonitor::ReadGPR. +/// Implements ProcessMonitor::ReadGPR. class ReadGPROperation : public Operation { public: ReadGPROperation(lldb::tid_t tid, void *buf, bool &result) @@ -438,7 +439,7 @@ void ReadGPROperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class ReadFPROperation -/// @brief Implements ProcessMonitor::ReadFPR. +/// Implements ProcessMonitor::ReadFPR. class ReadFPROperation : public Operation { public: ReadFPROperation(lldb::tid_t tid, void *buf, bool &result) @@ -461,7 +462,7 @@ void ReadFPROperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class WriteGPROperation -/// @brief Implements ProcessMonitor::WriteGPR. +/// Implements ProcessMonitor::WriteGPR. class WriteGPROperation : public Operation { public: WriteGPROperation(lldb::tid_t tid, void *buf, bool &result) @@ -484,7 +485,7 @@ void WriteGPROperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class WriteFPROperation -/// @brief Implements ProcessMonitor::WriteFPR. +/// Implements ProcessMonitor::WriteFPR. class WriteFPROperation : public Operation { public: WriteFPROperation(lldb::tid_t tid, void *buf, bool &result) @@ -507,7 +508,7 @@ void WriteFPROperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class ResumeOperation -/// @brief Implements ProcessMonitor::Resume. +/// Implements ProcessMonitor::Resume. class ResumeOperation : public Operation { public: ResumeOperation(uint32_t signo, bool &result) @@ -538,7 +539,7 @@ void ResumeOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class SingleStepOperation -/// @brief Implements ProcessMonitor::SingleStep. +/// Implements ProcessMonitor::SingleStep. class SingleStepOperation : public Operation { public: SingleStepOperation(uint32_t signo, bool &result) @@ -566,7 +567,7 @@ void SingleStepOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class LwpInfoOperation -/// @brief Implements ProcessMonitor::GetLwpInfo. +/// Implements ProcessMonitor::GetLwpInfo. class LwpInfoOperation : public Operation { public: LwpInfoOperation(lldb::tid_t tid, void *info, bool &result, int &ptrace_err) @@ -595,7 +596,7 @@ void LwpInfoOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class ThreadSuspendOperation -/// @brief Implements ProcessMonitor::ThreadSuspend. +/// Implements ProcessMonitor::ThreadSuspend. class ThreadSuspendOperation : public Operation { public: ThreadSuspendOperation(lldb::tid_t tid, bool suspend, bool &result) @@ -615,7 +616,7 @@ void ThreadSuspendOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class EventMessageOperation -/// @brief Implements ProcessMonitor::GetEventMessage. +/// Implements ProcessMonitor::GetEventMessage. class EventMessageOperation : public Operation { public: EventMessageOperation(lldb::tid_t tid, unsigned long *message, bool &result) @@ -645,7 +646,7 @@ void EventMessageOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class KillOperation -/// @brief Implements ProcessMonitor::Kill. +/// Implements ProcessMonitor::Kill. class KillOperation : public Operation { public: KillOperation(bool &result) : m_result(result) {} @@ -667,7 +668,7 @@ void KillOperation::Execute(ProcessMonitor *monitor) { //------------------------------------------------------------------------------ /// @class DetachOperation -/// @brief Implements ProcessMonitor::Detach. +/// Implements ProcessMonitor::Detach. class DetachOperation : public Operation { public: DetachOperation(Status &result) : m_error(result) {} @@ -714,11 +715,10 @@ ProcessMonitor::AttachArgs::~AttachArgs() {} //------------------------------------------------------------------------------ /// The basic design of the ProcessMonitor is built around two threads. /// -/// One thread (@see SignalThread) simply blocks on a call to waitpid() looking -/// for changes in the debugee state. When a change is detected a +/// One thread (@see SignalThread) simply blocks on a call to waitpid() +/// looking for changes in the debugee state. When a change is detected a /// ProcessMessage is sent to the associated ProcessFreeBSD instance. This -/// thread -/// "drives" state changes in the debugger. +/// thread "drives" state changes in the debugger. /// /// The second thread (@see OperationThread) is responsible for two things 1) /// launching or attaching to the inferior process, and then 2) servicing diff --git a/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.h b/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.h index c1c68f77644..1d3e2d746fa 100644 --- a/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.h +++ b/lldb/source/Plugins/Process/FreeBSD/ProcessMonitor.h @@ -32,10 +32,10 @@ class ProcessFreeBSD; class Operation; /// @class ProcessMonitor -/// @brief Manages communication with the inferior (debugee) process. +/// Manages communication with the inferior (debugee) process. /// -/// Upon construction, this class prepares and launches an inferior process for -/// debugging. +/// Upon construction, this class prepares and launches an inferior process +/// for debugging. /// /// Changes in the inferior process state are propagated to the associated /// ProcessFreeBSD instance by calling ProcessFreeBSD::SendMessage with the @@ -74,8 +74,7 @@ public: /// standard error of this debugee. Even if stderr and stdout were /// redirected on launch it may still happen that data is available on this /// descriptor (if the inferior process opens /dev/tty, for example). This - /// descriptor is - /// closed after a call to StopMonitor(). + /// descriptor is closed after a call to StopMonitor(). /// /// If this monitor was attached to an existing process this method returns /// -1. @@ -95,8 +94,8 @@ public: size_t WriteMemory(lldb::addr_t vm_addr, const void *buf, size_t size, lldb_private::Status &error); - /// Reads the contents from the register identified by the given (architecture - /// dependent) offset. + /// Reads the contents from the register identified by the given + /// (architecture dependent) offset. /// /// This method is provided for use by RegisterContextFreeBSD derivatives. bool ReadRegisterValue(lldb::tid_t tid, unsigned offset, const char *reg_name, @@ -215,8 +214,8 @@ private: /// @class LauchArgs /// - /// @brief Simple structure to pass data to the thread responsible for - /// launching a child process. + /// Simple structure to pass data to the thread responsible for launching a + /// child process. struct LaunchArgs : OperationArgs { LaunchArgs(ProcessMonitor *monitor, lldb_private::Module *module, char const **argv, lldb_private::Environment env, diff --git a/lldb/source/Plugins/Process/FreeBSD/RegisterContextPOSIX.h b/lldb/source/Plugins/Process/FreeBSD/RegisterContextPOSIX.h index 4ff5121bac1..97de5885605 100644 --- a/lldb/source/Plugins/Process/FreeBSD/RegisterContextPOSIX.h +++ b/lldb/source/Plugins/Process/FreeBSD/RegisterContextPOSIX.h @@ -20,7 +20,7 @@ //------------------------------------------------------------------------------ /// @class POSIXBreakpointProtocol /// -/// @brief Extends RegisterClass with a few virtual operations useful on POSIX. +/// Extends RegisterClass with a few virtual operations useful on POSIX. class POSIXBreakpointProtocol { public: POSIXBreakpointProtocol() { m_watchpoints_initialized = false; } diff --git a/lldb/source/Plugins/Process/Linux/NativeProcessLinux.h b/lldb/source/Plugins/Process/Linux/NativeProcessLinux.h index f078c1ac30e..dea7e61959a 100644 --- a/lldb/source/Plugins/Process/Linux/NativeProcessLinux.h +++ b/lldb/source/Plugins/Process/Linux/NativeProcessLinux.h @@ -31,10 +31,10 @@ class Scalar; namespace process_linux { /// @class NativeProcessLinux -/// @brief Manages communication with the inferior (debugee) process. +/// Manages communication with the inferior (debugee) process. /// -/// Upon construction, this class prepares and launches an inferior process for -/// debugging. +/// Upon construction, this class prepares and launches an inferior process +/// for debugging. /// /// Changes in the inferior process state are broadcasted. class NativeProcessLinux : public NativeProcessProtocol { diff --git a/lldb/source/Plugins/Process/NetBSD/NativeProcessNetBSD.h b/lldb/source/Plugins/Process/NetBSD/NativeProcessNetBSD.h index 7090fce34fc..142f74ecf19 100644 --- a/lldb/source/Plugins/Process/NetBSD/NativeProcessNetBSD.h +++ b/lldb/source/Plugins/Process/NetBSD/NativeProcessNetBSD.h @@ -20,10 +20,10 @@ namespace lldb_private { namespace process_netbsd { /// @class NativeProcessNetBSD -/// @brief Manages communication with the inferior (debugee) process. +/// Manages communication with the inferior (debugee) process. /// -/// Upon construction, this class prepares and launches an inferior process for -/// debugging. +/// Upon construction, this class prepares and launches an inferior process +/// for debugging. /// /// Changes in the inferior process state are broadcasted. class NativeProcessNetBSD : public NativeProcessProtocol { diff --git a/lldb/source/Plugins/Process/Utility/HistoryThread.h b/lldb/source/Plugins/Process/Utility/HistoryThread.h index 363ba266963..7675a95246a 100644 --- a/lldb/source/Plugins/Process/Utility/HistoryThread.h +++ b/lldb/source/Plugins/Process/Utility/HistoryThread.h @@ -29,13 +29,13 @@ namespace lldb_private { //---------------------------------------------------------------------- /// @class HistoryThread HistoryThread.h "HistoryThread.h" -/// @brief A thread object representing a backtrace from a previous point in the +/// A thread object representing a backtrace from a previous point in the /// process execution /// /// This subclass of Thread is used to provide a backtrace from earlier in /// process execution. It is given a backtrace list of pc addresses and -/// optionally a stop_id of when those pc addresses were collected, and it will -/// create stack frames for them. +/// optionally a stop_id of when those pc addresses were collected, and it +/// will create stack frames for them. //---------------------------------------------------------------------- class HistoryThread : public lldb_private::Thread { diff --git a/lldb/source/Plugins/Process/Utility/RegisterInfoInterface.h b/lldb/source/Plugins/Process/Utility/RegisterInfoInterface.h index 1894b536812..5d7ad89ad39 100644 --- a/lldb/source/Plugins/Process/Utility/RegisterInfoInterface.h +++ b/lldb/source/Plugins/Process/Utility/RegisterInfoInterface.h @@ -19,7 +19,7 @@ namespace lldb_private { ///------------------------------------------------------------------------------ /// @class RegisterInfoInterface /// -/// @brief RegisterInfo interface to patch RegisterInfo structure for archs. +/// RegisterInfo interface to patch RegisterInfo structure for archs. ///------------------------------------------------------------------------------ class RegisterInfoInterface { public: diff --git a/lldb/source/Symbol/ClangASTContext.cpp b/lldb/source/Symbol/ClangASTContext.cpp index 760f9131c94..87d347ff594 100644 --- a/lldb/source/Symbol/ClangASTContext.cpp +++ b/lldb/source/Symbol/ClangASTContext.cpp @@ -1391,7 +1391,7 @@ static TemplateParameterList *CreateTemplateParameterList( clang::FunctionTemplateDecl *ClangASTContext::CreateFunctionTemplateDecl( clang::DeclContext *decl_ctx, clang::FunctionDecl *func_decl, const char *name, const TemplateParameterInfos &template_param_infos) { - // /// \brief Create a function template node. + // /// Create a function template node. ASTContext *ast = getASTContext(); llvm::SmallVector<NamedDecl *, 8> template_param_decls; diff --git a/lldb/source/Utility/FastDemangle.cpp b/lldb/source/Utility/FastDemangle.cpp index cc045264c7b..d92670a9199 100644 --- a/lldb/source/Utility/FastDemangle.cpp +++ b/lldb/source/Utility/FastDemangle.cpp @@ -25,7 +25,7 @@ namespace { -/// @brief Represents the collection of qualifiers on a type +/// Represents the collection of qualifiers on a type enum Qualifiers { QualifierNone = 0, @@ -37,7 +37,7 @@ enum Qualifiers { QualifierPointer = 32 }; -/// @brief Categorizes the recognized operators +/// Categorizes the recognized operators enum class OperatorKind { Unary, @@ -50,23 +50,23 @@ enum class OperatorKind { NoMatch }; -/// @brief Represents one of the recognized two-character operator -/// abbreviations used when parsing operators as names and expressions +/// Represents one of the recognized two-character operator abbreviations used +/// when parsing operators as names and expressions struct Operator { const char *name; OperatorKind kind; }; -/// @brief Represents a range of characters in the output buffer, typically for -/// use with RewriteRange() +/// Represents a range of characters in the output buffer, typically for use +/// with RewriteRange() struct BufferRange { int offset; int length; }; -/// @brief Transient state required while parsing a name +/// Transient state required while parsing a name struct NameState { bool parse_function_params; @@ -75,12 +75,13 @@ struct NameState { BufferRange last_name_range; }; -/// @brief LLDB's fast C++ demangler +/// LLDB's fast C++ demangler /// /// This is an incomplete implementation designed to speed up the demangling /// process that is often a bottleneck when LLDB stops a process for the first /// time. Where the implementation doesn't know how to demangle a symbol it -/// fails gracefully to allow the caller to fall back to the existing demangler. +/// fails gracefully to allow the caller to fall back to the existing +/// demangler. /// /// Over time the full mangling spec should be supported without compromising /// performance for the most common cases. @@ -91,7 +92,7 @@ public: // Public API //---------------------------------------------------- - /// @brief Create a SymbolDemangler + /// Create a SymbolDemangler /// /// The newly created demangler allocates and owns scratch memory sufficient /// for demangling typical symbols. Additional memory will be allocated if @@ -107,18 +108,18 @@ public: m_owns_m_rewrite_ranges = true; } - /// @brief Create a SymbolDemangler that uses provided scratch memory + /// Create a SymbolDemangler that uses provided scratch memory /// /// The provided memory is not owned by the demangler. It will be - /// overwritten during calls to GetDemangledCopy() but can be used for - /// other purposes between calls. The provided memory will not be freed - /// when this instance is destroyed. + /// overwritten during calls to GetDemangledCopy() but can be used for other + /// purposes between calls. The provided memory will not be freed when this + /// instance is destroyed. /// /// If demangling a symbol requires additional space it will be allocated /// and managed by the demangler instance. /// - /// @param storage_ptr Valid pointer to at least storage_size bytes of - /// space that the SymbolDemangler can use during demangling + /// @param storage_ptr Valid pointer to at least storage_size bytes of space + /// that the SymbolDemangler can use during demangling /// /// @param storage_size Number of bytes of space available scratch memory /// referenced by storage_ptr @@ -138,8 +139,8 @@ public: m_owns_buffer = false; } - /// @brief Destroys the SymbolDemangler and deallocates any scratch - /// memory that it owns + /// Destroys the SymbolDemangler and deallocates any scratch memory that it + /// owns ~SymbolDemangler() { if (m_owns_buffer) @@ -153,11 +154,11 @@ public: int highwater_buffer = 0; #endif - /// @brief Parses the provided mangled name and returns a newly allocated + /// Parses the provided mangled name and returns a newly allocated /// demangling /// - /// @param mangled_name Valid null-terminated C++ mangled name following - /// the Itanium C++ ABI mangling specification as implemented by Clang + /// @param mangled_name Valid null-terminated C++ mangled name following the + /// Itanium C++ ABI mangling specification as implemented by Clang /// /// @result Newly allocated null-terminated demangled name when demangling /// is successful, and nullptr when demangling fails. The caller is diff --git a/lldb/tools/debugserver/source/JSONGenerator.h b/lldb/tools/debugserver/source/JSONGenerator.h index a85dcb6e860..7af6ae60c5f 100644 --- a/lldb/tools/debugserver/source/JSONGenerator.h +++ b/lldb/tools/debugserver/source/JSONGenerator.h @@ -21,7 +21,7 @@ //---------------------------------------------------------------------- /// @class JSONGenerator JSONGenerator.h -/// @brief A class which can construct structured data for the sole purpose +/// A class which can construct structured data for the sole purpose /// of printing it in JSON format. /// /// A stripped down version of lldb's StructuredData objects which are much diff --git a/lldb/tools/intel-features/intel-pt/Decoder.h b/lldb/tools/intel-features/intel-pt/Decoder.h index dc2794ac3bc..3762196058f 100644 --- a/lldb/tools/intel-features/intel-pt/Decoder.h +++ b/lldb/tools/intel-features/intel-pt/Decoder.h @@ -33,7 +33,7 @@ namespace ptdecoder_private { //---------------------------------------------------------------------- /// @class Instruction -/// @brief Represents an assembly instruction containing raw +/// Represents an assembly instruction containing raw /// instruction bytes, instruction address along with information /// regarding execution flow context and Intel(R) Processor Trace /// context. @@ -83,7 +83,7 @@ private: //--------------------------------------------------------------------------- /// @class InstructionList -/// @brief Represents a list of assembly instructions. Each instruction is of +/// Represents a list of assembly instructions. Each instruction is of /// type Instruction. //--------------------------------------------------------------------------- class InstructionList { @@ -113,7 +113,7 @@ private: //---------------------------------------------------------------------- /// @class TraceOptions -/// @brief Provides Intel(R) Processor Trace specific configuration options and +/// Provides Intel(R) Processor Trace specific configuration options and /// other information obtained by decoding and post-processing the trace /// data. Currently, this information comprises of the total number of /// assembly instructions executed for an inferior. @@ -147,7 +147,7 @@ private: //---------------------------------------------------------------------- /// @class Decoder -/// @brief This class makes use of Intel(R) Processor Trace hardware feature +/// This class makes use of Intel(R) Processor Trace hardware feature /// (implememted inside LLDB) to gather trace data for an inferior (being /// debugged with LLDB) to provide meaningful information out of it. /// diff --git a/lldb/tools/intel-features/intel-pt/PTDecoder.h b/lldb/tools/intel-features/intel-pt/PTDecoder.h index 9eb92745a86..8af8c8672b1 100644 --- a/lldb/tools/intel-features/intel-pt/PTDecoder.h +++ b/lldb/tools/intel-features/intel-pt/PTDecoder.h @@ -33,7 +33,7 @@ namespace ptdecoder { //---------------------------------------------------------------------- /// @class PTInstruction -/// @brief Represents an assembly instruction containing raw +/// Represents an assembly instruction containing raw /// instruction bytes, instruction address along with information /// regarding execution flow context and Intel(R) Processor Trace /// context. @@ -85,7 +85,7 @@ private: //--------------------------------------------------------------------------- /// @class PTInstructionList -/// @brief Represents a list of assembly instructions. Each instruction is of +/// Represents a list of assembly instructions. Each instruction is of /// type PTInstruction. //--------------------------------------------------------------------------- class PTInstructionList { @@ -114,7 +114,7 @@ private: //---------------------------------------------------------------------- /// @class PTTraceOptions -/// @brief Provides configuration options like trace type, trace buffer size, +/// Provides configuration options like trace type, trace buffer size, /// meta data buffer size along with other Intel(R) Processor Trace /// specific options. //---------------------------------------------------------------------- @@ -134,9 +134,9 @@ public: //------------------------------------------------------------------ /// Get Intel(R) Processor Trace specific configuration options (apart from - /// trace buffer size, meta data buffer size and TraceType) formatted as json - /// text i.e. {"Name":Value,"Name":Value} pairs, where "Value" is a 64-bit - /// unsigned integer in hex format. For "Name", please refer to + /// trace buffer size, meta data buffer size and TraceType) formatted as + /// json text i.e. {"Name":Value,"Name":Value} pairs, where "Value" is a + /// 64-bit unsigned integer in hex format. For "Name", please refer to /// SBProcess::StartTrace API description for setting SBTraceOptions. /// /// @return @@ -154,7 +154,7 @@ private: //---------------------------------------------------------------------- /// @class PTDecoder -/// @brief This class makes use of Intel(R) Processor Trace hardware feature +/// This class makes use of Intel(R) Processor Trace hardware feature /// (implememted inside LLDB) to gather trace data for an inferior (being /// debugged with LLDB) to provide meaningful information out of it. /// |