[Lldb-commits] Improving the documentation

[John Lindal via lldb-commits]

Having completed my C++ app on top of lldb, I would like to improve the
function-level documentation so others don't have to blunder around in the
dark the way I did :)

Here is a patch for SBAddress.h

If this is the right direction, I will work my way through the rest of the
SB*.h files.

Thanks!
John Lindal

-----

diff --git a/include/lldb/API/SBAddress.h b/include/lldb/API/SBAddress.h
index 4cbbee9..b324e90 100644
--- a/include/lldb/API/SBAddress.h
+++ b/include/lldb/API/SBAddress.h
@@ -33,27 +33,100 @@ public:
     const lldb::SBAddress &
     operator = (const lldb::SBAddress &rhs);

+    //------------------------------------------------------------------
+    /// @return
+    ///     true if the object is valid.  If the object is invalid, it is
+    ///     not safe to call any other methods.
+    //------------------------------------------------------------------
     bool
     IsValid () const;

+    //------------------------------------------------------------------
+    /// Clears the address.  The object is no longer valid.
+    //------------------------------------------------------------------
     void
     Clear ();

+    //------------------------------------------------------------------
+    /// 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 a unique section in the object file.
+    ///
+    /// @return
+    ///     The valid file virtual address, or LLDB_INVALID_ADDRESS if
+    ///     the address doesn't have a file virtual address (image is
+    ///     from memory only with no representation on disk).
+    //------------------------------------------------------------------
     addr_t
     GetFileAddress () const;

+    //------------------------------------------------------------------
+    /// 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 a 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.
+    ///
+    /// @param[in] target
+    ///     The target in which to search.
+    ///
+    /// @return
+    ///     The valid load virtual address, or LLDB_INVALID_ADDRESS if
+    ///     the address is currently not loaded.
+    //------------------------------------------------------------------
     addr_t
     GetLoadAddress (const lldb::SBTarget &target) const;

+    //------------------------------------------------------------------
+    /// Set the section and address within the section.  If it succeeds,
+    /// the object becomes valid.
+    ///
+    /// @param[in] section
+    ///     A lldb::SBSection object to use as the section base.
+    ///
+    /// @param[in] offset
+    ///     A new offset value for this object.
+    //------------------------------------------------------------------
     void
     SetAddress (lldb::SBSection section, lldb::addr_t offset);

+    //------------------------------------------------------------------
+    /// Tries to resolve the address within the target.  If this fails,
+    /// assumes the address is absolute, e.g., on the stack or heap.  If it
+    /// succeeds, the object becomes valid.
+    ///
+    /// @param[in] load_addr
+    ///     A new offset value for this object.
+    ///
+    /// @param[in] target
+    ///     The target within which the offset is valid.
+    //------------------------------------------------------------------
     void
     SetLoadAddress (lldb::addr_t load_addr,
                     lldb::SBTarget &target);
+
+    //------------------------------------------------------------------
+    /// Set the offset for this address, relative to the current section,
+    /// if any.
+    ///
+    /// @param[in] offset
+    ///     A new offset value for this object.
+    //------------------------------------------------------------------
+    // FIXME:  Should this be SetOffsetAddress?
     bool
     OffsetAddress (addr_t offset);

+    //------------------------------------------------------------------
+    /// Dump a description of this object to the given lldb::SBStream.
+    ///
+    /// @param[in] description
+    ///     The stream to which to dump the object description.
+    //------------------------------------------------------------------
     bool
     GetDescription (lldb::SBStream &description);

@@ -63,10 +136,25 @@ public:
     // will only return valid values if the address has been resolved to a
code
     // or data address using "void SBAddress::SetLoadAddress(...)" or
     // "lldb::SBAddress SBTarget::ResolveLoadAddress (...)".
+
+    //------------------------------------------------------------------
+    /// Lookup symbol information for this address.  An address might
+    /// refer to code or data from an existing module, or it might refer to
+    /// something on the stack or heap. This function will only return
+    /// valid values if the address has been resolved to a code or data
+    /// address using "void SBAddress::SetLoadAddress(...)" or
+    /// "lldb::SBAddress SBTarget::ResolveLoadAddress (...)".
+    ///
+    /// @param[in] resolve_scope
+    ///     lldb::SymbolContextItem value specifying the scope in which to
+    ///     resolve this address.
+    ///
+    /// @return
+    ///     lldb::SBSymbolContext with the result.
+    //------------------------------------------------------------------
     lldb::SBSymbolContext
     GetSymbolContext (uint32_t resolve_scope);

-
     // The following functions grab individual objects for a given address
and
     // are less efficient if you want more than one symbol related
objects.
     // Use one of the following when you want multiple debug symbol
related
@@ -76,30 +164,67 @@ public:
     // One or more bits from the SymbolContextItem enumerations can be
logically
     // OR'ed together to more efficiently retrieve multiple symbol objects.

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The lldb::SBSection containing this address.
+    //------------------------------------------------------------------
     lldb::SBSection
     GetSection ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The offset for this address, relative to the section.
+    //------------------------------------------------------------------
     lldb::addr_t
     GetOffset ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The module containing this address.
+    //------------------------------------------------------------------
     lldb::SBModule
     GetModule ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The compile unit containing this address.
+    //------------------------------------------------------------------
     lldb::SBCompileUnit
     GetCompileUnit ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The function containing this address.
+    //------------------------------------------------------------------
     lldb::SBFunction
     GetFunction ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The block containing this address.
+    //------------------------------------------------------------------
     lldb::SBBlock
     GetBlock ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The symbol at this address.
+    //------------------------------------------------------------------
     lldb::SBSymbol
     GetSymbol ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The lldb::SBLineEntry specifying the file location that
+    ///     corresponds to this address.
+    //------------------------------------------------------------------
     lldb::SBLineEntry
     GetLineEntry ();

+    //------------------------------------------------------------------
+    /// @return section
+    ///     The classification for this address.
+    //------------------------------------------------------------------
     lldb::AddressClass
     GetAddressClass ();
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20160309/b0c9a919/attachment-0001.html>