* [binutils-gdb] Don't use chew comments for static functions
@ 2023-02-20 21:35 Tom Tromey
0 siblings, 0 replies; only message in thread
From: Tom Tromey @ 2023-02-20 21:35 UTC (permalink / raw)
To: bfd-cvs
https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=2070491c1c31b254b1e8f2250144777a23e9f616
commit 2070491c1c31b254b1e8f2250144777a23e9f616
Author: Tom Tromey <tom@tromey.com>
Date: Fri Feb 17 12:12:11 2023 -0700
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 <tom@tromey.com>
* 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:
---
bfd/ChangeLog | 7 +++
bfd/opncls.c | 170 ++++++++++++++++++----------------------------------------
2 files changed, 58 insertions(+), 119 deletions(-)
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 <tom@tromey.com>
+
+ * 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 <tom@tromey.com>
* 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)
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2023-02-20 21:35 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-20 21:35 [binutils-gdb] Don't use chew comments for static functions Tom Tromey
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).