From: Tom Tromey <tom@tromey.com>
To: binutils@sourceware.org
Cc: Tom Tromey <tom@tromey.com>
Subject: [PATCH 2/4] Don't use chew comments for static functions
Date: Fri, 17 Feb 2023 12:29:03 -0700 [thread overview]
Message-ID: <20230217192905.3160819-3-tom@tromey.com> (raw)
In-Reply-To: <20230217192905.3160819-1-tom@tromey.com>
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.
bfd/ChangeLog
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.
---
bfd/ChangeLog | 7 +++
bfd/opncls.c | 170 +++++++++++++++-----------------------------------
2 files changed, 58 insertions(+), 119 deletions(-)
diff --git a/bfd/opncls.c b/bfd/opncls.c
index eeac5825dbf..95906526973 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -1165,29 +1165,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)
@@ -1322,22 +1313,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)
@@ -1365,17 +1346,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)
@@ -1393,33 +1364,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 *);
@@ -1818,23 +1778,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)
@@ -1919,25 +1870,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)
@@ -1981,21 +1922,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)
--
2.39.1
next prev parent reply other threads:[~2023-02-17 19:29 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-17 19:29 [PATCH 0/4] More fixes to chew documentation Tom Tromey
2023-02-17 19:29 ` [PATCH 1/4] Fix formatting of long function description in chew output Tom Tromey
2023-02-17 19:29 ` Tom Tromey [this message]
2023-02-17 19:29 ` [PATCH 3/4] Hoist the SECTION comment in opncls.c Tom Tromey
2023-02-17 19:29 ` [PATCH 4/4] Redefine FUNCTION in doc.str Tom Tromey
2023-02-20 14:59 ` [PATCH 0/4] More fixes to chew documentation Nick Clifton
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230217192905.3160819-3-tom@tromey.com \
--to=tom@tromey.com \
--cc=binutils@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).