<div dir="ltr">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 :)<div><br></div><div>Here is a patch for SBAddress.h</div><div><br></div><div>If this is the right direction, I will work my way through the rest of the SB*.h files.</div><div><br></div><div>Thanks!</div><div>John Lindal</div><div><br></div><div>-----</div><div><br></div><div><div>diff --git a/include/lldb/API/SBAddress.h b/include/lldb/API/SBAddress.h</div><div>index 4cbbee9..b324e90 100644</div><div>--- a/include/lldb/API/SBAddress.h</div><div>+++ b/include/lldb/API/SBAddress.h</div><div>@@ -33,27 +33,100 @@ public:</div><div>     const lldb::SBAddress &</div><div>     operator = (const lldb::SBAddress &rhs);</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return</div><div>+    ///     true if the object is valid.  If the object is invalid, it is</div><div>+    ///     not safe to call any other methods.</div><div>+    //------------------------------------------------------------------</div><div>     bool</div><div>     IsValid () const;</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// Clears the address.  The object is no longer valid.</div><div>+    //------------------------------------------------------------------</div><div>     void</div><div>     Clear ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// Get the file address.</div><div>+    ///</div><div>+    /// If an address comes from a file on disk that has section</div><div>+    /// relative addresses, then it has a virtual address that is</div><div>+    /// relative to a unique section in the object file.</div><div>+    ///</div><div>+    /// @return</div><div>+    ///     The valid file virtual address, or LLDB_INVALID_ADDRESS if</div><div>+    ///     the address doesn't have a file virtual address (image is</div><div>+    ///     from memory only with no representation on disk).</div><div>+    //------------------------------------------------------------------</div><div>     addr_t</div><div>     GetFileAddress () const;</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// Get the load address.</div><div>+    ///</div><div>+    /// If an address comes from a file on disk that has section</div><div>+    /// relative addresses, then it has a virtual address that is</div><div>+    /// relative to a unique section in the object file. Sections</div><div>+    /// get resolved at runtime by DynamicLoader plug-ins as images</div><div>+    /// (executables and shared libraries) get loaded/unloaded. If a</div><div>+    /// section is loaded, then the load address can be resolved.</div><div>+    ///</div><div>+    /// @param[in] target</div><div>+    ///     The target in which to search.</div><div>+    ///</div><div>+    /// @return</div><div>+    ///     The valid load virtual address, or LLDB_INVALID_ADDRESS if</div><div>+    ///     the address is currently not loaded.</div><div>+    //------------------------------------------------------------------</div><div>     addr_t</div><div>     GetLoadAddress (const lldb::SBTarget &target) const;</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// Set the section and address within the section.  If it succeeds,</div><div>+    /// the object becomes valid.</div><div>+    ///</div><div>+    /// @param[in] section</div><div>+    ///     A lldb::SBSection object to use as the section base.</div><div>+    ///</div><div>+    /// @param[in] offset</div><div>+    ///     A new offset value for this object.</div><div>+    //------------------------------------------------------------------</div><div>     void</div><div>     SetAddress (lldb::SBSection section, lldb::addr_t offset);</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// Tries to resolve the address within the target.  If this fails,</div><div>+    /// assumes the address is absolute, e.g., on the stack or heap.  If it</div><div>+    /// succeeds, the object becomes valid.</div><div>+    ///</div><div>+    /// @param[in] load_addr</div><div>+    ///     A new offset value for this object.</div><div>+    ///</div><div>+    /// @param[in] target</div><div>+    ///     The target within which the offset is valid.</div><div>+    //------------------------------------------------------------------</div><div>     void</div><div>     SetLoadAddress (lldb::addr_t load_addr, </div><div>                     lldb::SBTarget &target);</div><div>+</div><div>+    //------------------------------------------------------------------</div><div>+    /// Set the offset for this address, relative to the current section,</div><div>+    /// if any.</div><div>+    ///</div><div>+    /// @param[in] offset</div><div>+    ///     A new offset value for this object.</div><div>+    //------------------------------------------------------------------</div><div>+    // FIXME:  Should this be SetOffsetAddress?</div><div>     bool</div><div>     OffsetAddress (addr_t offset);</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// Dump a description of this object to the given lldb::SBStream.</div><div>+    ///</div><div>+    /// @param[in] description</div><div>+    ///     The stream to which to dump the object description.</div><div>+    //------------------------------------------------------------------</div><div>     bool</div><div>     GetDescription (lldb::SBStream &description);</div><div> </div><div>@@ -63,10 +136,25 @@ public:</div><div>     // will only return valid values if the address has been resolved to a code</div><div>     // or data address using "void SBAddress::SetLoadAddress(...)" or </div><div>     // "lldb::SBAddress SBTarget::ResolveLoadAddress (...)". </div><div>+</div><div>+    //------------------------------------------------------------------</div><div>+    /// Lookup symbol information for this address.  An address might</div><div>+    /// refer to code or data from an existing module, or it might refer to</div><div>+    /// something on the stack or heap. This function will only return</div><div>+    /// valid values if the address has been resolved to a code or data</div><div>+    /// address using "void SBAddress::SetLoadAddress(...)" or</div><div>+    /// "lldb::SBAddress SBTarget::ResolveLoadAddress (...)".</div><div>+    ///</div><div>+    /// @param[in] resolve_scope</div><div>+    ///     lldb::SymbolContextItem value specifying the scope in which to</div><div>+    ///     resolve this address.</div><div>+    ///</div><div>+    /// @return</div><div>+    ///     lldb::SBSymbolContext with the result.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBSymbolContext</div><div>     GetSymbolContext (uint32_t resolve_scope);</div><div> </div><div>-    </div><div>     // The following functions grab individual objects for a given address and</div><div>     // are less efficient if you want more than one symbol related objects. </div><div>     // Use one of the following when you want multiple debug symbol related </div><div>@@ -76,30 +164,67 @@ public:</div><div>     // One or more bits from the SymbolContextItem enumerations can be logically</div><div>     // OR'ed together to more efficiently retrieve multiple symbol objects.</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The lldb::SBSection containing this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBSection</div><div>     GetSection ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The offset for this address, relative to the section.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::addr_t</div><div>     GetOffset ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The module containing this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBModule</div><div>     GetModule ();</div><div>     </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The compile unit containing this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBCompileUnit</div><div>     GetCompileUnit ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The function containing this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBFunction</div><div>     GetFunction ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The block containing this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBBlock</div><div>     GetBlock ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The symbol at this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBSymbol</div><div>     GetSymbol ();</div><div> </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The lldb::SBLineEntry specifying the file location that</div><div>+    ///     corresponds to this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::SBLineEntry</div><div>     GetLineEntry ();</div><div>     </div><div>+    //------------------------------------------------------------------</div><div>+    /// @return section</div><div>+    ///     The classification for this address.</div><div>+    //------------------------------------------------------------------</div><div>     lldb::AddressClass</div><div>     GetAddressClass ();</div><div> </div></div><div><br></div></div>