From: Tom Tromey <tom@tromey.com>
To: binutils@sourceware.org
Cc: Tom Tromey <tom@tromey.com>
Subject: [PATCH 8/8] Remove RETURNS from BFD chew comments
Date: Wed, 8 Feb 2023 00:17:25 -0700 [thread overview]
Message-ID: <20230208071725.3668898-9-tom@tromey.com> (raw)
In-Reply-To: <20230208071725.3668898-1-tom@tromey.com>
When reading the BFD manual, I noticed text like this:
-- Function: bool bfd_close (bfd *abfd);
Close a BFD. If the BFD was open for writing, then pending
operations are completed and the file written out and closed. If
...
*Returns*
'TRUE' is returned if all is ok, otherwise 'FALSE'.
The *Returns*, like the *Synopsis* in the earlier patch, is
un-info-like. It's also used inconsistently.
This patch removes all the uses of the RETURNS word and removes it
entirely from the chew scripts. Now this example reads:
-- Function: bool bfd_close (bfd *abfd);
Close a BFD. If the BFD was open for writing, then pending
operations are completed and the file written out and closed. If
...
'TRUE' is returned if all is ok, otherwise 'FALSE'.
In a few cases I had to slightly reword the comment. There were also
a couple of cases where there was redundant text. In these cases I
just dropped the RETURNS copy.
2023-02-07 Tom Tromey <tom@tromey.com>
* bfd.c, cache.c, compress.c, opncls.c: Remove RETURNS from
documentation comments.
* doc/doc.str, doc/proto.str (RETURNS): Remove.
---
bfd/ChangeLog | 6 ++++++
bfd/bfd.c | 9 --------
bfd/cache.c | 2 --
bfd/compress.c | 3 ---
bfd/doc/doc.str | 3 ---
bfd/doc/proto.str | 1 -
bfd/opncls.c | 53 ++++++++++++++++++-----------------------------
7 files changed, 26 insertions(+), 51 deletions(-)
diff --git a/bfd/bfd.c b/bfd/bfd.c
index c59e31d99e2..3624bfbc9a5 100644
--- a/bfd/bfd.c
+++ b/bfd/bfd.c
@@ -1841,7 +1841,6 @@ DESCRIPTION
header. Use bfd_arch_bits_per_address for number of bits in
the architecture address.
-RETURNS
Returns the arch size in bits if known, <<-1>> otherwise.
*/
@@ -1869,7 +1868,6 @@ DESCRIPTION
return an address sign extended to fill a bfd_vma when this is
the case.
-RETURNS
Returns <<1>> if the target architecture is known to sign
extend addresses, <<0>> if the target architecture is known to
not sign extend addresses, and <<-1>> otherwise.
@@ -1921,7 +1919,6 @@ SYNOPSIS
DESCRIPTION
Make @var{vma} the entry point of output BFD @var{abfd}.
-RETURNS
Returns <<TRUE>> on success, <<FALSE>> otherwise.
*/
@@ -2485,9 +2482,6 @@ SYNOPSIS
DESCRIPTION
Returns the maximum page size, in bytes, as determined by
emulation.
-
-RETURNS
- Returns the maximum page size in bytes for ELF, 0 otherwise.
*/
bfd_vma
@@ -2513,9 +2507,6 @@ SYNOPSIS
DESCRIPTION
Returns the common page size, in bytes, as determined by
emulation.
-
-RETURNS
- Returns the common page size in bytes for ELF, 0 otherwise.
*/
bfd_vma
diff --git a/bfd/cache.c b/bfd/cache.c
index b64b9744c4b..ab36c8506bd 100644
--- a/bfd/cache.c
+++ b/bfd/cache.c
@@ -521,7 +521,6 @@ DESCRIPTION
Remove the BFD @var{abfd} from the cache. If the attached file is open,
then close it too.
-RETURNS
<<FALSE>> is returned if closing the file fails, <<TRUE>> is
returned if all is well.
*/
@@ -550,7 +549,6 @@ DESCRIPTION
Remove all BFDs from the cache. If the attached file is open,
then close it too.
-RETURNS
<<FALSE>> is returned if closing one of the file fails, <<TRUE>> is
returned if all is well.
*/
diff --git a/bfd/compress.c b/bfd/compress.c
index 2cf8a6c28c9..43bdb9ebf44 100644
--- a/bfd/compress.c
+++ b/bfd/compress.c
@@ -263,9 +263,6 @@ SYNOPSIS
DESCRIPTION
Return the size of the compression header of SEC in ABFD.
-
-RETURNS
- Return the size of the compression header in bytes.
*/
int
diff --git a/bfd/doc/doc.str b/bfd/doc/doc.str
index 4576d497521..2a0953a3ece 100644
--- a/bfd/doc/doc.str
+++ b/bfd/doc/doc.str
@@ -124,9 +124,6 @@ variable synopsis_seen
0 synopsis_seen !
;
-: RETURNS
- "@strong{Returns}@*\n" catstr subhead ;
-
: INTERNAL_FUNCTION
func ;
diff --git a/bfd/doc/proto.str b/bfd/doc/proto.str
index 5206f7f3877..3b776736067 100644
--- a/bfd/doc/proto.str
+++ b/bfd/doc/proto.str
@@ -144,7 +144,6 @@
: INTERNAL_DEFINITION internal ;
: DESCRIPTION ignore ;
: FUNCTION external ;
-: RETURNS ignore ;
: TYPEDEF external ;
: INTERNAL_FUNCTION internal ;
: INTERNAL internal ;
diff --git a/bfd/opncls.c b/bfd/opncls.c
index 6ae3af054e4..9ee032c4ac5 100644
--- a/bfd/opncls.c
+++ b/bfd/opncls.c
@@ -798,7 +798,6 @@ DESCRIPTION
The file descriptor associated with the BFD is closed (even
if it was passed in to BFD by <<bfd_fdopenr>>).
-RETURNS
<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
*/
@@ -829,7 +828,6 @@ DESCRIPTION
All memory attached to the BFD is released.
-RETURNS
<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
*/
@@ -903,7 +901,6 @@ DESCRIPTION
by converting the BFD to BFD_IN_MEMORY. It's assumed that
you will call <<bfd_make_readable>> on this bfd later.
-RETURNS
<<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
*/
@@ -949,7 +946,6 @@ DESCRIPTION
contents out to the memory buffer, then reversing the
direction.
-RETURNS
<<TRUE>> is returned if all is ok, otherwise <<FALSE>>. */
bool
@@ -1096,7 +1092,6 @@ DESCRIPTION
Advances the previously computed @var{crc} value by computing
and adding in the crc32 for @var{len} bytes of @var{buf}.
-RETURNS
Return the updated CRC32 value.
*/
@@ -1184,11 +1179,10 @@ DESCRIPTION
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.
@@ -1250,11 +1244,10 @@ DESCRIPTION
Extracts the filename and CRC32 value for any separate debug
information file associated with @var{abfd}.
-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.
@@ -1422,7 +1415,6 @@ DESCRIPTION
functions. It is generally used to implement build-id-like
matching in the callback functions.
-RETURNS
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.
@@ -1606,10 +1598,10 @@ DESCRIPTION
If @var{dir} is NULL, the search will take place starting at
the current directory.
-RETURNS
- <<NULL>> on any errors or failure to locate the .debug file,
- otherwise a pointer to a heap-allocated string containing the
- filename. The caller is responsible for freeing this string.
+ Returns <<NULL>> on any errors or failure to locate the .debug
+ file, otherwise a pointer to a heap-allocated string
+ containing the filename. The caller is responsible for
+ freeing this string.
*/
char *
@@ -1655,10 +1647,10 @@ DESCRIPTION
If @var{dir} is NULL, the search will take place starting at
the current directory.
-RETURNS
- <<NULL>> on any errors or failure to locate the debug file,
- otherwise a pointer to a heap-allocated string containing the
- filename. The caller is responsible for freeing this string.
+ Returns <<NULL>> on any errors or failure to locate the debug
+ file, otherwise a pointer to a heap-allocated string
+ containing the filename. The caller is responsible for
+ freeing this string.
*/
char *
@@ -1683,7 +1675,6 @@ DESCRIPTION
section is sized to be big enough to contain a link to the specified
@var{filename}.
-RETURNS
A pointer to the new section is returned if all is ok. Otherwise
<<NULL>> is returned and bfd_error is set.
*/
@@ -1751,7 +1742,6 @@ DESCRIPTION
specified @var{filename}. The filename should be relative to the
current directory.
-RETURNS
<<TRUE>> is returned if all is ok. Otherwise <<FALSE>> is returned
and bfd_error is set.
*/
@@ -1840,7 +1830,6 @@ DESCRIPTION
for it, using memory allocated to @var{abfd}, and this is then
attached to the @var{abfd}.
-RETURNS
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.
@@ -1941,7 +1930,6 @@ DESCRIPTION
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
Returns the constructed filename or NULL upon error.
It is the caller's responsibility to free the memory used to hold the
filename.
@@ -2003,7 +1991,6 @@ DESCRIPTION
Checks to see if @var{name} is a readable file and if its build-id
matches @var{buildid}.
-RETURNS
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 **}).
@@ -2070,10 +2057,10 @@ DESCRIPTION
If @var{dir} is NULL, the search will take place starting at
the current directory.
-RETURNS
- <<NULL>> on any errors or failure to locate the debug file,
- otherwise a pointer to a heap-allocated string containing the
- filename. The caller is responsible for freeing this string.
+ Returns <<NULL>> on any errors or failure to locate the debug
+ file, otherwise a pointer to a heap-allocated string
+ containing the filename. The caller is responsible for
+ freeing this string.
*/
char *
--
2.39.1
next prev parent reply other threads:[~2023-02-08 7:17 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-02-08 7:17 [PATCH 0/8] Make the BFD info manual a bit prettier Tom Tromey
2023-02-08 7:17 ` [PATCH 1/8] Remove H_CFLAGS from doc/local.mk Tom Tromey
2023-02-08 7:17 ` [PATCH 2/8] Simplify @node use in BFD documentation Tom Tromey
2023-03-03 8:20 ` Jan Beulich
2023-03-03 23:08 ` Tom Tromey
2023-03-06 7:07 ` Jan Beulich
2023-02-08 7:17 ` [PATCH 3/8] Add copyright headers to the .str files Tom Tromey
2023-02-08 7:17 ` [PATCH 4/8] Remove the paramstuff word Tom Tromey
2023-02-08 7:17 ` [PATCH 5/8] Use intptr_t rather than long in chew Tom Tromey
2023-02-08 7:17 ` [PATCH 6/8] Change internalmode to be an intrinsic variable Tom Tromey
2023-02-08 7:17 ` [PATCH 7/8] Use @deftypefn in chew output Tom Tromey
2023-02-15 17:55 ` Simon Marchi
2023-02-15 23:11 ` Tom Tromey
2023-02-16 1:29 ` Simon Marchi
2023-02-19 3:46 ` Alan Modra
2023-02-08 7:17 ` Tom Tromey [this message]
2023-02-15 9:54 ` [PATCH 0/8] Make the BFD info manual a bit prettier Nick Clifton
2023-02-15 21:51 ` Tom Tromey
2023-02-16 9:40 ` 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=20230208071725.3668898-9-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).