[PATCH] libdw: Update dwarf_cu_dwp_section_info documentation

[PATCH] libdw: Update dwarf_cu_dwp_section_info documentation

[Mark Wielaard]

Update the documentation of dwarf_cu_dwp_section_info to make clear
that the function only returns an error if the DWARF package file data
couldn't be read or an unknown section constant is provided.  Missing
DWP information for a given CU isn't an error and will set both OFFSET
and SIZE to zero.  It also makes sure the documentation is < 76 chars
wide.

	* libdw/libdw.h (dwarf_cu_dwp_section_info): Update docs.

Signed-off-by: Mark Wielaard <mark@klomp.org>
---
 libdw/libdw.h | 42 +++++++++++++++++++++++-------------------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/libdw/libdw.h b/libdw/libdw.h
index 545ad043..d53dc787 100644
--- a/libdw/libdw.h
+++ b/libdw/libdw.h
@@ -1081,25 +1081,29 @@ extern int dwarf_frame_register (Dwarf_Frame *frame, int regno,
   __nonnull_attribute__ (3, 4, 5);
 
 
-/* Return offset and/or size of CU's contribution to SECTION in a DWARF package
-   file.
-
-   If CU is not from a DWARF package file, the file does not have SECTION, or CU
-   does not contribute to SECTION, then *SIZEP is set to 0.
-
-   SECTION is a DW_SECT section identifier.  Note that the original GNU DWARF
-   package file extension for DWARF 4 used slightly different section
-   identifiers.  This function uses the standardized section identifiers and
-   maps the GNU DWARF 4 identifiers to their standard DWARF 5 analogues:
-   DW_SECT_LOCLISTS (5) refers to .debug_locs.dwo for DWARF 4.
-   DW_SECT_MACRO (7) refers to .debug_macinfo.dwo for DWARF 4 or
-   .debug_macro.dwo for the GNU .debug_macro extension for DWARF 4 (section
-   identifier 8 is DW_SECT_RNGLISTS in DWARF 5, NOT DW_SECT_MACRO like in the
-   GNU extension.)
-   .debug_types.dwo does not have a DWARF 5 equivalent, so this function accepts
-   the original DW_SECT_TYPES (2).
-
-   Returns 0 for success or -1 for errors.  OFFSETP and SIZEP may be NULL.  */
+/* Return offset and/or size of CU's contribution to SECTION in a
+   DWARF package file.
+
+   If CU is not from a DWARF package file, the file does not have
+   SECTION, or CU does not contribute to SECTION, then *OFFSETP and
+   *SIZEP are set to 0 (this is not an error and the function will
+   return 0 in that case).
+
+   SECTION is a DW_SECT section identifier.  Note that the original
+   GNU DWARF package file extension for DWARF 4 used slightly
+   different section identifiers.  This function uses the standardized
+   section identifiers and maps the GNU DWARF 4 identifiers to their
+   standard DWARF 5 analogues: DW_SECT_LOCLISTS (5) refers to
+   .debug_locs.dwo for DWARF 4.  DW_SECT_MACRO (7) refers to
+   .debug_macinfo.dwo for DWARF 4 or .debug_macro.dwo for the GNU
+   .debug_macro extension for DWARF 4 (section identifier 8 is
+   DW_SECT_RNGLISTS in DWARF 5, NOT DW_SECT_MACRO like in the GNU
+   extension.)  .debug_types.dwo does not have a DWARF 5 equivalent,
+   so this function accepts the original DW_SECT_TYPES (2).
+
+   Returns 0 for success or -1 for errors reading the DWARF package
+   file data or if an unknown SECTION constant is given.  OFFSETP and
+   SIZEP may be NULL.  */
 extern int dwarf_cu_dwp_section_info (Dwarf_CU *cu, unsigned int section,
 				      Dwarf_Off *offsetp, Dwarf_Off *sizep);
 
-- 
2.43.2

Re: [PATCH] libdw: Update dwarf_cu_dwp_section_info documentation

[Omar Sandoval]

On Fri, Feb 16, 2024 at 02:34:18PM +0100, Mark Wielaard wrote:
> Update the documentation of dwarf_cu_dwp_section_info to make clear
> that the function only returns an error if the DWARF package file data
> couldn't be read or an unknown section constant is provided.  Missing
> DWP information for a given CU isn't an error and will set both OFFSET
> and SIZE to zero.  It also makes sure the documentation is < 76 chars
> wide.
> 
> 	* libdw/libdw.h (dwarf_cu_dwp_section_info): Update docs.
> 
> Signed-off-by: Mark Wielaard <mark@klomp.org>

This looks good to me, thanks Mark.

Re: [PATCH] libdw: Update dwarf_cu_dwp_section_info documentation

[Mark Wielaard]

Hi Omar,

On Thu, Feb 22, 2024 at 09:54:29AM -0800, Omar Sandoval wrote:
> On Fri, Feb 16, 2024 at 02:34:18PM +0100, Mark Wielaard wrote:
> > Update the documentation of dwarf_cu_dwp_section_info to make clear
> > that the function only returns an error if the DWARF package file data
> > couldn't be read or an unknown section constant is provided.  Missing
> > DWP information for a given CU isn't an error and will set both OFFSET
> > and SIZE to zero.  It also makes sure the documentation is < 76 chars
> > wide.
> > 
> > 	* libdw/libdw.h (dwarf_cu_dwp_section_info): Update docs.
> > 
> > Signed-off-by: Mark Wielaard <mark@klomp.org>
> 
> This looks good to me, thanks Mark.

Thanks for the review. Pushed.

Cheers,

Mark