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.

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)

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

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.
 */

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

bfd/doc/doc.str

@@ -124,9 +124,6 @@ variable synopsis_seen
 	0 synopsis_seen !
 	;
 
-: RETURNS
-	"@strong{Returns}@*\n" catstr subhead ;
-
 : INTERNAL_FUNCTION
 	func ;
 

bfd/doc/proto.str

@@ -144,7 +144,6 @@
 : INTERNAL_DEFINITION internal ;
 : DESCRIPTION ignore ;
 : FUNCTION external ;
-: RETURNS ignore ;
 : TYPEDEF external ;
 : INTERNAL_FUNCTION internal ;
 : INTERNAL internal ;

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 *