From: Tom Tromey Date: Wed, 8 Feb 2023 04:43:37 +0000 (-0700) Subject: Remove RETURNS from BFD chew comments X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=f370ae88a81ce5775c008e9509a53d34d6707d65;p=binutils-gdb.git 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 * 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 6a8d5b1612a..e160e4472df 100644 --- a/bfd/ChangeLog +++ b/bfd/ChangeLog @@ -1,3 +1,9 @@ +2023-02-07 Tom Tromey + + * 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 * 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 <> on success, <> 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 <> is returned if closing the file fails, <> 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 <> is returned if closing one of the file fails, <> 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 <>). -RETURNS <> is returned if all is ok, otherwise <>. */ @@ -829,7 +828,6 @@ DESCRIPTION All memory attached to the BFD is released. -RETURNS <> is returned if all is ok, otherwise <>. */ @@ -903,7 +901,6 @@ DESCRIPTION by converting the BFD to BFD_IN_MEMORY. It's assumed that you will call <> on this bfd later. -RETURNS <> is returned if all is ok, otherwise <>. */ @@ -949,7 +946,6 @@ DESCRIPTION contents out to the memory buffer, then reversing the direction. -RETURNS <> is returned if all is ok, otherwise <>. */ 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 - <> 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 <> 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 - <> 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 <> 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 <> 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 <> is returned if all is ok. Otherwise <> 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 - <> 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 <> 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 *