From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gproxy3-pub.mail.unifiedlayer.com (gproxy3-pub.mail.unifiedlayer.com [69.89.30.42]) by sourceware.org (Postfix) with ESMTPS id 637003858C30 for ; Wed, 8 Feb 2023 07:17:45 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 637003858C30 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=tromey.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=tromey.com Received: from cmgw13.mail.unifiedlayer.com (unknown [10.0.90.128]) by progateway5.mail.pro1.eigbox.com (Postfix) with ESMTP id D88C010047D77 for ; Wed, 8 Feb 2023 07:17:44 +0000 (UTC) Received: from box5379.bluehost.com ([162.241.216.53]) by cmsmtp with ESMTP id Pei8pszj8NX2aPei8peBuC; Wed, 08 Feb 2023 07:17:44 +0000 X-Authority-Reason: nr=8 X-Authority-Analysis: v=2.4 cv=NMAQR22g c=1 sm=1 tr=0 ts=63e34c98 a=ApxJNpeYhEAb1aAlGBBbmA==:117 a=ApxJNpeYhEAb1aAlGBBbmA==:17 a=dLZJa+xiwSxG16/P+YVxDGlgEgI=:19 a=m04uMKEZRckA:10:nop_rcvd_month_year a=Qbun_eYptAEA:10:endurance_base64_authed_username_1 a=zstS-IiYAAAA:8 a=lsXRvnW9D21-jYZLWeYA:9 a=4G6NA9xxw8l3yy4pmD5M:22 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tromey.com; s=default; h=Content-Transfer-Encoding:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:Cc:To:From:Sender:Reply-To:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=0qzt+tfGFlyF2tWN8iX0piTjfBzy6VphB9RV+c1VobU=; b=AKURgc8+O2Zf1lTu6g43wi64XU DJ6Ei/ciGzMcUpbD3nMeAUUeF5RYRBe7zXwp6xTcJ+AklRSznxAeH9EKbbq8+a93k7s4yJEhu5GAw fa1o48SyG1d5B9iEa8R+igGJB; Received: from 75-166-130-93.hlrn.qwest.net ([75.166.130.93]:55392 helo=localhost.localdomain) by box5379.bluehost.com with esmtpsa (TLS1.2) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.95) (envelope-from ) id 1pPei8-002znH-Kv; Wed, 08 Feb 2023 00:17:44 -0700 From: Tom Tromey To: binutils@sourceware.org Cc: Tom Tromey Subject: [PATCH 8/8] Remove RETURNS from BFD chew comments Date: Wed, 8 Feb 2023 00:17:25 -0700 Message-Id: <20230208071725.3668898-9-tom@tromey.com> X-Mailer: git-send-email 2.39.1 In-Reply-To: <20230208071725.3668898-1-tom@tromey.com> References: <20230208071725.3668898-1-tom@tromey.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-AntiAbuse: This header was added to track abuse, please include it with any abuse report X-AntiAbuse: Primary Hostname - box5379.bluehost.com X-AntiAbuse: Original Domain - sourceware.org X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12] X-AntiAbuse: Sender Address Domain - tromey.com X-BWhitelist: no X-Source-IP: 75.166.130.93 X-Source-L: No X-Exim-ID: 1pPei8-002znH-Kv X-Source: X-Source-Args: X-Source-Dir: X-Source-Sender: 75-166-130-93.hlrn.qwest.net (localhost.localdomain) [75.166.130.93]:55392 X-Source-Auth: tom+tromey.com X-Email-Count: 9 X-Source-Cap: ZWx5bnJvYmk7ZWx5bnJvYmk7Ym94NTM3OS5ibHVlaG9zdC5jb20= X-Local-Domain: yes X-Spam-Status: No, score=-3028.2 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,GIT_PATCH_0,JMQ_SPF_NEUTRAL,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: 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. --- 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 <> 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 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 <>). -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 @@ -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 - <> 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 * @@ -1655,10 +1647,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 * @@ -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 <> 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 <> is returned if all is ok. Otherwise <> 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 - <> 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 * -- 2.39.1