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 --git a/bfd/ChangeLog b/bfd/ChangeLog
index 6a8d5b1612a28d44f841743964bb1fccac6572a4..e160e4472dfc595b029b64b8fa9a8ff8f36def3f 100644 (file)
--- 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 c59e31d99e209bd63be06c36cceefa4c7e91c7b0..3624bfbc9a5e9135a17e574c21f0d9965d1302b4 100644 (file)
--- 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 b64b9744c4b6e0aeda9c18a5b41de81e9293d9f1..ab36c8506bda5b5e2660595d6a64636173a6409f 100644 (file)
--- 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 2a402c3f65c40ac9be5dd5b6b64442a5dc2eebb5..39f9c50a44575b1119650abb6e08c9051c174f96 100644 (file)
--- 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 4576d497521558a005e8f305e77d3051c67715c9..2a0953a3ece4b5f64997be4e71bd0ca5632cb263 100644 (file)
--- 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 5206f7f38777a71380e8dd1280fd0c075d6116c6..3b77673606718c928c91b66b70362cfb5d4ff154 100644 (file)
--- 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 4dbd30d2fe95085ba510a79fe9b13d2c80aa1cb8..eeac5825dbf9cb9f02b049d8ea4a6937e196ad45 100644 (file)
--- 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 *