From: Tom Tromey Date: Fri, 17 Feb 2023 19:12:11 +0000 (-0700) Subject: Don't use chew comments for static functions X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=2070491c1c31b254b1e8f2250144777a23e9f616;p=binutils-gdb.git Don't use chew comments for static functions I found a few static functions in the BFD manual. These can't be called by any user of the library, so I don't think it's useful to put them in the manual. This patch removes the chew markup from their comments. 2023-02-17 Tom Tromey * opncls.c (bfd_get_debug_link_info_1, separate_debug_file_exists) (separate_alt_debug_file_exists, find_separate_debug_file) (get_build_id, get_build_id_name, check_build_id_file): Don't use chew comments. --- diff --git a/bfd/ChangeLog b/bfd/ChangeLog index 2b487818721..a974a5c6716 100644 --- a/bfd/ChangeLog +++ b/bfd/ChangeLog @@ -1,3 +1,10 @@ +2023-02-17 Tom Tromey + + * opncls.c (bfd_get_debug_link_info_1, separate_debug_file_exists) + (separate_alt_debug_file_exists, find_separate_debug_file) + (get_build_id, get_build_id_name, check_build_id_file): Don't use + chew comments. + 2023-02-17 Tom Tromey * doc/doc.str (SYNOPSIS): Use collapse_whitespace. diff --git a/bfd/opncls.c b/bfd/opncls.c index f0f4ed55ca4..3fa2b03fdf9 100644 --- a/bfd/opncls.c +++ b/bfd/opncls.c @@ -1171,29 +1171,20 @@ bfd_calc_gnu_debuglink_crc32 (unsigned long crc, } -/* -INTERNAL_FUNCTION - bfd_get_debug_link_info_1 - -SYNOPSIS - char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out); - -DESCRIPTION - Extracts the filename and CRC32 value for any separate debug - information file associated with @var{abfd}. +/* Extracts the filename and CRC32 value for any separate debug + information file associated with @var{abfd}. - The @var{crc32_out} parameter is an untyped pointer because - this routine is used as a @code{get_func_type} function, but it - is expected to be an unsigned long pointer. + The @var{crc32_out} parameter is an untyped pointer because + this routine is used as a @code{get_func_type} function, but it + is expected to be an unsigned long pointer. - Returns the filename of the associated debug information file, - or NULL if there is no such file. If the filename was found - then the contents of @var{crc32_out} are updated to hold the - corresponding CRC32 value for the file. + Returns the filename of the associated debug information file, + or NULL if there is no such file. If the filename was found + then the contents of @var{crc32_out} are updated to hold the + corresponding CRC32 value for the file. - The returned filename is allocated with @code{malloc}; freeing - it is the responsibility of the caller. -*/ + The returned filename is allocated with @code{malloc}; freeing + it is the responsibility of the caller. */ static char * bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out) @@ -1328,22 +1319,12 @@ bfd_get_alt_debug_link_info (bfd * abfd, bfd_size_type *buildid_len, return name; } -/* -INTERNAL_FUNCTION - separate_debug_file_exists - -SYNOPSIS - bool separate_debug_file_exists - (char *name, void *crc32_p); - -DESCRIPTION - Checks to see if @var{name} is a file and if its contents - match @var{crc32}, which is a pointer to an @code{unsigned - long} containing a CRC32. +/* Checks to see if @var{name} is a file and if its contents match + @var{crc32}, which is a pointer to an @code{unsigned long} + containing a CRC32. - The @var{crc32_p} parameter is an untyped pointer because - this routine is used as a @code{check_func_type} function. -*/ + The @var{crc32_p} parameter is an untyped pointer because this + routine is used as a @code{check_func_type} function. */ static bool separate_debug_file_exists (const char *name, void *crc32_p) @@ -1371,17 +1352,7 @@ separate_debug_file_exists (const char *name, void *crc32_p) return crc == file_crc; } -/* -INTERNAL_FUNCTION - separate_alt_debug_file_exists - -SYNOPSIS - bool separate_alt_debug_file_exists - (char *name, void *unused); - -DESCRIPTION - Checks to see if @var{name} is a file. -*/ +/* Checks to see if @var{name} is a file. */ static bool separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED) @@ -1399,33 +1370,22 @@ separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED) return true; } -/* -INTERNAL_FUNCTION - find_separate_debug_file +/* Searches for a debug information file corresponding to @var{abfd}. -SYNOPSIS - char *find_separate_debug_file - (bfd *abfd, const char *dir, bool include_dirs, - get_func_type get, check_func_type check, void *data); + The name of the separate debug info file is returned by the + @var{get} function. This function scans various fixed locations + in the filesystem, including the file tree rooted at @var{dir}. + If the @var{include_dirs} parameter is true then the directory + components of @var{abfd}'s filename will be included in the + searched locations. -DESCRIPTION - Searches for a debug information file corresponding to @var{abfd}. - - The name of the separate debug info file is returned by the - @var{get} function. This function scans various fixed locations - in the filesystem, including the file tree rooted at @var{dir}. - If the @var{include_dirs} parameter is true then the directory - components of @var{abfd}'s filename will be included in the - searched locations. - - @var{data} is passed unmodified to the @var{get} and @var{check} - functions. It is generally used to implement build-id-like - matching in the callback functions. - - Returns the filename of the first file to be found which - receives a TRUE result from the @var{check} function. - Returns NULL if no valid file could be found. -*/ + @var{data} is passed unmodified to the @var{get} and @var{check} + functions. It is generally used to implement build-id-like + matching in the callback functions. + + Returns the filename of the first file to be found which + receives a TRUE result from the @var{check} function. + Returns NULL if no valid file could be found. */ typedef char * (*get_func_type) (bfd *, void *); typedef bool (*check_func_type) (const char *, void *); @@ -1824,23 +1784,14 @@ bfd_fill_in_gnu_debuglink_section (bfd *abfd, return true; } -/* -INTERNAL_FUNCTION - get_build_id - -SYNOPSIS - struct bfd_build_id * get_build_id (bfd *abfd); +/* Finds the build-id associated with @var{abfd}. If the build-id is + extracted from the note section then a build-id structure is built + for it, using memory allocated to @var{abfd}, and this is then + attached to the @var{abfd}. -DESCRIPTION - Finds the build-id associated with @var{abfd}. If the build-id is - extracted from the note section then a build-id structure is built - for it, using memory allocated to @var{abfd}, and this is then - attached to the @var{abfd}. - - Returns a pointer to the build-id structure if a build-id could be - found. If no build-id is found NULL is returned and error code is - set. -*/ + Returns a pointer to the build-id structure if a build-id could be + found. If no build-id is found NULL is returned and error code is + set. */ static struct bfd_build_id * get_build_id (bfd *abfd) @@ -1925,25 +1876,15 @@ get_build_id (bfd *abfd) return build_id; } -/* -INTERNAL_FUNCTION - get_build_id_name - -SYNOPSIS - char * get_build_id_name (bfd *abfd, void *build_id_out_p) +/* Searches @var{abfd} for a build-id, and then constructs a pathname + from it. The path is computed as .build-id/NN/NN+NN.debug where + NNNN+NN is the build-id value as a hexadecimal string. -DESCRIPTION - Searches @var{abfd} for a build-id, and then constructs a pathname - from it. The path is computed as .build-id/NN/NN+NN.debug where - NNNN+NN is the build-id value as a hexadecimal string. - - Returns the constructed filename or NULL upon error. - It is the caller's responsibility to free the memory used to hold the - filename. - If a filename is returned then the @var{build_id_out_p} - parameter (which points to a @code{struct bfd_build_id} - pointer) is set to a pointer to the build_id structure. -*/ + Returns the constructed filename or NULL upon error. It is the + caller's responsibility to free the memory used to hold the + filename. If a filename is returned then the @var{build_id_out_p} + parameter (which points to a @code{struct bfd_build_id} pointer) is + set to a pointer to the build_id structure. */ static char * get_build_id_name (bfd *abfd, void *build_id_out_p) @@ -1987,21 +1928,12 @@ get_build_id_name (bfd *abfd, void *build_id_out_p) return name; } -/* -INTERNAL_FUNCTION - check_build_id_file +/* Checks to see if @var{name} is a readable file and if its build-id + matches @var{buildid}. -SYNOPSIS - bool check_build_id_file (char *name, void *buildid_p); - -DESCRIPTION - Checks to see if @var{name} is a readable file and if its build-id - matches @var{buildid}. - - Returns TRUE if the file exists, is readable, and contains a - build-id which matches the build-id pointed at by - @var{build_id_p} (which is really a @code{struct bfd_build_id **}). -*/ + Returns TRUE if the file exists, is readable, and contains a + build-id which matches the build-id pointed at by @var{build_id_p} + (which is really a @code{struct bfd_build_id **}). */ static bool check_build_id_file (const char *name, void *buildid_p)