Correcting/updating debuglink doc and example

	modified:   doc/checkexamples.c
	modified:   src/lib/libdwarf/libdwarf.h

Author: davea42

doc/checkexamples.c

@@ -1066,60 +1066,40 @@ int exampleg(Dwarf_Debug dbg, Dwarf_Error *error)
     return DW_DLV_OK;
 }
 
-void exampleh(Dwarf_Debug dbg)
+int exampleh(Dwarf_Debug dbg,Dwarf_Error *error)
 {
-    Dwarf_Error error = 0;
     Dwarf_Signed count = 0;
     Dwarf_Weak *weaks = 0;
     Dwarf_Signed i = 0;
     int res = 0;
 
-    res = dwarf_get_weaks(dbg, &weaks, &count, &error);
-    if (res == DW_DLV_OK) {
-        for (i = 0; i < count; ++i) {
-            /* use weaks[i] */
-        }
-        dwarf_weaks_dealloc(dbg, weaks, count);
+    res = dwarf_get_weaks(dbg, &weaks, &count, error);
+    if (res != DW_DLV_OK) {
+        return res;
     }
-}
-
-/* example of what not to do. */
-void examplei(Dwarf_Debug dbg)
-{
-    Dwarf_Error error = 0;
-    Dwarf_Signed count = 0;
-    Dwarf_Weak *weaks = 0;
-    Dwarf_Signed i = 0;
-    int res = 0;
-
-    /* Obsolete, see exampleh instead */
-    res = dwarf_get_weaks(dbg, &weaks, &count, &error);
-    if (res == DW_DLV_OK) {
-        /*  OBSOLETE: do not use dealloc for this.
-            See above */
-        for (i = 0; i < count; ++i) {
-            /* use weaks[i] */
-            dwarf_dealloc(dbg, weaks[i], DW_DLA_WEAK);
-        }
-        dwarf_dealloc(dbg, weaks, DW_DLA_LIST);
+    for (i = 0; i < count; ++i) {
+        /* use weaks[i] */
     }
+    dwarf_weaks_dealloc(dbg, weaks, count);
+    return DW_DLV_OK;
 }
 
-void examplej(Dwarf_Debug dbg)
+int examplej(Dwarf_Debug dbg, Dwarf_Error*error)
 {
-    Dwarf_Error error = 0;
     Dwarf_Signed count = 0;
     Dwarf_Func *funcs = 0;
     Dwarf_Signed i = 0;
     int fres = 0;
 
-    fres = dwarf_get_funcs(dbg, &funcs, &count, &error);
-    if (fres == DW_DLV_OK) {
-        for (i = 0; i < count; ++i) {
-            /* use funcs[i] */
-        }
-        dwarf_funcs_dealloc(dbg, funcs, count);
+    fres = dwarf_get_funcs(dbg, &funcs, &count, error);
+    if (fres != DW_DLV_OK) {
+        return fres;
     }
+    for (i = 0; i < count; ++i) {
+        /* use funcs[i] */
+    }
+    dwarf_funcs_dealloc(dbg, funcs, count);
+    return DW_DLV_OK;
 }
 
 void examplek(Dwarf_Debug dbg)

src/lib/libdwarf/libdwarf.h

@@ -6874,11 +6874,12 @@ DW_API int dwarf_get_debugfission_for_key(Dwarf_Debug /*dbg*/,
     @{
 */
 
-/*  New October 2019.  Access to the GNU section named
+/*! @brief Find a separated DWARF object file
+
     .gnu_debuglink  and/or the section .note.gnu.build-id.
-    See
-    https://sourceware.org/gdb/onlinedocs/gdb/
-        Separate-Debug-Files.html
+
+    @see https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html
+    @see exampledebuglink
 
     If no debuglink then name_returned,crc_returned and
     debuglink_path_returned will get set 0 through the pointers.
@@ -6887,11 +6888,7 @@ DW_API int dwarf_get_debugfission_for_key(Dwarf_Debug /*dbg*/,
     and buildid_returned will be set 0 through the pointers.
 
     Caller frees space returned by debuglink_fullpath_returned.
-
-    See libdwarf2.1.mm revision 3.13 or later for
-    additional important details.
 */
-
 DW_API int dwarf_gnu_debuglink(Dwarf_Debug /*dbg*/,
     char     **    /*debuglink_path_returned */,
     unsigned char ** /*crc_returned from the debuglink section*/,