* [binutils-gdb] Remove RETURNS from BFD chew comments
@ 2023-02-15 17:28 Tom Tromey
0 siblings, 0 replies; only message in thread
From: Tom Tromey @ 2023-02-15 17:28 UTC (permalink / raw)
To: bfd-cvs
https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=f370ae88a81ce5775c008e9509a53d34d6707d65
commit f370ae88a81ce5775c008e9509a53d34d6707d65
Author: Tom Tromey <tom@tromey.com>
Date: Tue Feb 7 21:43:37 2023 -0700
Remove RETURNS from BFD chew comments
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.
Diff:
---
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/ChangeLog b/bfd/ChangeLog
index 6a8d5b1612a..e160e4472df 100644
--- a/bfd/ChangeLog
+++ b/bfd/ChangeLog
@@ -1,3 +1,9 @@
+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.
+
2023-02-07 Tom Tromey <tom@tromey.com>
* syms.c (bfd_decode_symclass, bfd_is_undefined_symclass)
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 2a402c3f65c..39f9c50a445 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 4dbd30d2fe9..eeac5825dbf 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
@@ -1097,7 +1093,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.
*/
@@ -1185,11 +1180,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.
@@ -1251,11 +1245,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.
@@ -1423,7 +1416,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.
@@ -1607,10 +1599,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 *
@@ -1656,10 +1648,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 *
@@ -1684,7 +1676,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.
*/
@@ -1752,7 +1743,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.
*/
@@ -1841,7 +1831,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.
@@ -1942,7 +1931,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.
@@ -2004,7 +1992,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 **}).
@@ -2071,10 +2058,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 *
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2023-02-15 17:28 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-02-15 17:28 [binutils-gdb] Remove RETURNS from BFD chew comments 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).