From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx0a-00069f02.pphosted.com (mx0a-00069f02.pphosted.com [205.220.165.32]) by sourceware.org (Postfix) with ESMTPS id BA57C3858420 for ; Fri, 17 May 2024 12:18:55 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org BA57C3858420 Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=oracle.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=oracle.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org BA57C3858420 Authentication-Results: server2.sourceware.org; arc=pass smtp.remote-ip=205.220.165.32 ARC-Seal: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1715948337; cv=pass; b=OG5P8V6qHIy7IuRY18lRYR77llDI/lSaj3bQg/B3NvgkcIWX6BNqemlPnd0I1XNx+kkOCju+TWsQ6QPQevWZh1xfu1DpTlW+r5L7OAEIGarrHgHWku4Puq6fqAfdoBxw//lDvEcSDJmeL/SWvWDByO/HdU7KYwlzk1OK/O2/bt8= ARC-Message-Signature: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1715948337; c=relaxed/simple; bh=v71Qk4yp94+QuFPzYHcIW3qKlNZ8Tt+L/nsw5pKB+Xs=; h=DKIM-Signature:DKIM-Signature:From:To:Subject:Date:Message-ID: MIME-Version; b=P2s+sZilQrcnQTBNhnuD7lWlauOW0LvzTwHsgBagS4lJZ+2FxHjUVf9syKOavHgbazby9r5BZQZGzudH9Jzi3f0jRFA0rTdPxBgguRBhVpgOsv00mpw3Ufv2QKSZX+ePY59/8oxX+OfOXk50+/WPSIlJNlhQtCZbE/GKLn1ee3Y= ARC-Authentication-Results: i=2; server2.sourceware.org Received: from pps.filterd (m0246627.ppops.net [127.0.0.1]) by mx0b-00069f02.pphosted.com (8.17.1.19/8.17.1.19) with ESMTP id 44HCIsZD012459 for ; Fri, 17 May 2024 12:18:54 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=from : to : subject : references : date : in-reply-to : message-id : content-type : mime-version; s=corp-2023-11-20; bh=FLRS+uOcTt48BQtXnv+ABBpGagpnlxDe6AP4GV1BZxM=; b=eMHcuPTHwKIgK8uqDpZqGKBW2HBk5V4RsURfQ9gBtqlEanMywxy6YcBxayckshwN9JpS 6ab50tV34eX0Af4rjSCbOycOa55gVKiuQU9EUsnAoWbYGFpAi0iSJbAyKlaP4WuhuXQK JW45IT/n08C87XIAGK4Mix+4aBSFKlZ7O9wm8V42TgOrCUidvYOkIJWAPHU0MTw5VGxM Ep9sS7kgX233/VJRHhr1F0oUgNNofpT2F2ncOAh78TVrIv2MLCi2+tktqYEjotUJOIpY ChY4pxaHqgipVphX5BlypBNRgmVzC3+31d3/nWZtsTPQ7lQSx8LEgCPU8aPicFSbpVMr 4w== Received: from phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com (phxpaimrmta02.appoci.oracle.com [147.154.114.232]) by mx0b-00069f02.pphosted.com (PPS) with ESMTPS id 3y3t4ryssr-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 17 May 2024 12:18:53 +0000 Received: from pps.filterd (phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com [127.0.0.1]) by phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com (8.17.1.19/8.17.1.19) with ESMTP id 44HB7mvH001127 for ; Fri, 17 May 2024 12:04:40 GMT Received: from nam10-bn7-obe.outbound.protection.outlook.com (mail-bn7nam10lp2100.outbound.protection.outlook.com [104.47.70.100]) by phxpaimrmta02.imrmtpd1.prodappphxaev1.oraclevcn.com (PPS) with ESMTPS id 3y4fsutr4e-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 17 May 2024 12:04:40 +0000 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=NpBXor24lgphUhIMns1F4HbIRf07ml+mpwMSqLAfze3FdMuh1Jn1OHBk5w4I+AfWudMaiKp3BSsYn1ryNjM22Zf0ZKAXIl7jvSpej6mefHrw4ENbDMcSEVQCouM1KID8QzxfzlcTKNgUN/BlYEgz5jLLeFly7TnLqVOpbiCWl+QfSpYFagjnWJGhF5uVRl+Jo1X4iQ0Mf1GzAWERqbWJje7n7+xOIp3hkI88ZzvJI8PzAgwee0fh/8FXMMGxFwH1FDJpFv0cDj0iW0wJoWVWNiwy/JRTsuVzXTK/fj5gDuAijZ9m6RvH0z056b5M6w0lc4Dcvj9rBiNqt0IrhJf8dg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1; bh=FLRS+uOcTt48BQtXnv+ABBpGagpnlxDe6AP4GV1BZxM=; b=Z5NdlHOqbwKjPBqM5AUj/pb7nxqXZJV1jE1rxDbiwQEIGHbUOYAkPQv9YDZxKjjFy/LtlIEZ69BS6u3TcjPq3LKxVQKQQ3AFUrhkZmohIC+JRy3ZjCmBdHDaxpc8C2hg5eEi8908RM4fG+FfeKj9W3YIJRh4wPdQv7NSlKZdVPldZwgzH+apBy7Pkx1UXU5ZD3mPRhRKh2wdC2IloNxf8nV8SEefFBVYejYMYUSpL/GJx7Sd3ZatE8dZHWiX2FR5QSUXBMhCQ82Wo5TDBeMswKTSSwSht0BuZ3J0WhCEfV4f4yaMI84aBfNBcUUR3ed42tsaHCRzDlFEKtgLijwJxg== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=oracle.com; dmarc=pass action=none header.from=oracle.com; dkim=pass header.d=oracle.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.onmicrosoft.com; s=selector2-oracle-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=FLRS+uOcTt48BQtXnv+ABBpGagpnlxDe6AP4GV1BZxM=; b=SWp8MZJa/e+9oPlpVVRXuCJHImOp714XyBz63IZtvs6MqFhrlL2GnAMBqtmlxidqsys470+r147XXDCXLZ5T6Pv1ZEN0H4RuxIokI75HFSIzl1GhFh83+IY8F+P/kSt2gs2wijuk4CJAptGaPlueo/pqGPe+/znizbmUnaL62xE= Received: from MW4PR10MB6608.namprd10.prod.outlook.com (2603:10b6:303:22e::8) by DM6PR10MB4186.namprd10.prod.outlook.com (2603:10b6:5:218::14) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.7587.27; Fri, 17 May 2024 12:04:38 +0000 Received: from MW4PR10MB6608.namprd10.prod.outlook.com ([fe80::f9b2:8c8b:841a:aff3]) by MW4PR10MB6608.namprd10.prod.outlook.com ([fe80::f9b2:8c8b:841a:aff3%3]) with mapi id 15.20.7587.028; Fri, 17 May 2024 12:04:38 +0000 From: Nick Alcock To: binutils@sourceware.org Subject: Re: [PATCH] include, libctf: add a bunch of documentation to ctf-api.h References: <20240514124224.205190-1-nick.alcock@oracle.com> Emacs: because editing your files should be a traumatic experience. Date: Fri, 17 May 2024 13:04:30 +0100 In-Reply-To: <20240514124224.205190-1-nick.alcock@oracle.com> (Nick Alcock's message of "Tue, 14 May 2024 13:42:23 +0100") Message-ID: <87wmns4pbl.fsf@esperi.org.uk> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.3 (gnu/linux) Content-Type: text/plain X-ClientProxiedBy: LO4P265CA0052.GBRP265.PROD.OUTLOOK.COM (2603:10a6:600:2ac::15) To MW4PR10MB6608.namprd10.prod.outlook.com (2603:10b6:303:22e::8) MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-TrafficTypeDiagnostic: MW4PR10MB6608:EE_|DM6PR10MB4186:EE_ X-MS-Office365-Filtering-Correlation-Id: 23acc964-55fa-4368-7870-08dc7669866e X-MS-Exchange-SenderADCheck: 1 X-MS-Exchange-AntiSpam-Relay: 0 X-Microsoft-Antispam: BCL:0;ARA:13230031|1800799015|366007|376005; X-Microsoft-Antispam-Message-Info: =?us-ascii?Q?KHEkqCiI7/695NBQ8sENlvlG1HLPux345E/jxkveeUwnt5+cjbVffDolaJHj?= =?us-ascii?Q?DnsAFQQOHW+cmZupzupj2OZ4RX6lwPUShct0fHmfrgw9I9p8iapEYBsR/CtE?= =?us-ascii?Q?IbbmnFYA0rqBiuHyuBjvBomygHOd32V76aTwS5V+MZWJnGh6S0MXlPs5ij+I?= =?us-ascii?Q?tznmbFD/hSpOMk3zIPOpdFXxNz4Lt1yxtNjp/ZvZMMBSMkQmZ4pdcfNHbWnG?= =?us-ascii?Q?3DxEU2I++lyr97GZAM4fhDzpm/6U+G9O0fbfx8/QSj+SyHJVIYLPbotUO1dN?= =?us-ascii?Q?ZIbNEjCIaLAOZBenZ/jtOsWHv1ReOJmaOncwirGnzXbw4i0g18su5XO143/+?= =?us-ascii?Q?2ZO3kRsnbTngviDKjcH0XEwL9ZxbK7FZ0SNqRvN64zl+OBIQ6j657Ddrjp57?= =?us-ascii?Q?8fBetXfD60VRLxgQaXrC2R71Sq6OvVEkcSioKhVhuQVL6B9cxxOclkD87SuM?= =?us-ascii?Q?nmVTIkrOTTeCVu/Un/OEX43WOFCj6zO82IsCmjlZ/T9O6VjkSsdrOI/un46I?= =?us-ascii?Q?PikuP+D60y1dyjnk24c6flgMBC46dSUtQcY50mI8E7qQn/Ac9pZXQANKyBkb?= =?us-ascii?Q?ozXm5/yoHTudIfRVlShm+fLcLkdcVP1+chY08sI6xsPffoZbDr6joo3Ir20h?= =?us-ascii?Q?a2HFZFpxutrQLQ7hcldOt8udhq9npyLH9io4D7EtqthlGdAolcyZ048gjIJG?= =?us-ascii?Q?9MCXsVYthIkUqYzVPViQF0oUIQak2QqI1jkuSlubzuyLMzHsZ5+e+7RQg90X?= =?us-ascii?Q?Acgrwi4pNx8gCZdXnNXidUmzBceGhhoP2QntcPsSykdoUNk5UbHDmyJ7LluC?= =?us-ascii?Q?pPh4oPEMsaQ43vz+6Qm3JEPV9PzENL6knwUGQcvXjpZ0Qe4gaqJy9e0A2Gpk?= =?us-ascii?Q?PwVnZR3KimHJyMLMOdzX0fndnqrJLu7Nz6kiRB6CQjFAx3zx1Jy4Lm7f8DEB?= =?us-ascii?Q?hYyZi6tA3paZm9N0zU908okVt+02zIC3IseJsBsCQGPRgRrq9nV5am/UDvSb?= =?us-ascii?Q?ygSux2yqXwOsE69w/FPk/5jQeUJj6s+fKjMLnJcKDDXNAq/hobQAhV5HcDjg?= =?us-ascii?Q?Ge5oHUgo8SDM/b+NMYQ64pt0Z8VSnTNdNVMYACSK/jvq3kHOyAI+emE4XMfD?= =?us-ascii?Q?1ObIO9uGmJM5xE1VATLkFbCDiaYc/YVIyrqfxPaEJjdFw2Q99KtnGwo6POi1?= =?us-ascii?Q?7pLrSTlVwoCzTqAfGc9b2hJ3hZG83nD9QkinUr9e9g8cZ58IAypEIJyUrfZ/?= =?us-ascii?Q?92bJpmgLgAvfTvASwOonR5k43Pynjr7G/RB9xe9qYw=3D=3D?= X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:1;SRV:;IPV:NLI;SFV:NSPM;H:MW4PR10MB6608.namprd10.prod.outlook.com;PTR:;CAT:NONE;SFS:(13230031)(1800799015)(366007)(376005);DIR:OUT;SFP:1101; X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?sFDk139UvagtmxxGhgZFV7RoxBphJB7nQEKML0uUFdH+FbBKCnu8LFxVtjWn?= =?us-ascii?Q?k7P+98ECYkBFFl2NvPgGZAtGyw9NB39mZ+CiKehDw7ZoN7+bUe7pZ6mzZBkH?= =?us-ascii?Q?JzLF7xts8FqioRwxWfHM/DVqke4X4pCzsWMLqwZr9WIRyhZaWDwHIITz3X/a?= =?us-ascii?Q?AoVGdl+XZo9JUNMHqbBxrRBZofGSt5O7zHtgLCpkAYxLx+PG3H1n/ccyE5vp?= =?us-ascii?Q?HuorG68lz0TrFhPZrpMb4PoZ/qtoCuSvRLamZ8Z6o441OPwfRBT44497sSMp?= =?us-ascii?Q?jg6HVmoqNy66IE8+tNhzvZ1JEAC+v0l9WIKdk8fN32AJ/YjM2UELAAbGzm++?= =?us-ascii?Q?ZiGCM4dn8m7y5wJxGtTe6QDWVjOkGh8HKcBlTH3q/J3NffUInzqRF4O925Od?= =?us-ascii?Q?VfYqdDsS1rL+xlLHSMsHhf9Dd/RlR+ztNLYf07H6R/9+y6MOLzlcXDGQ2RS+?= =?us-ascii?Q?TpEp4dppeMzIX5jqnfVZAGpE4uz9eAXwMv8ft4HLW52vG+gaCfoo6oe0hVDC?= =?us-ascii?Q?yZ/jbqZzjrLX4PsYM2makZ1g2BFnk/AMwCpG27emqxwo7ct7CVzaCzbG1qnO?= =?us-ascii?Q?ST4zHEXnAcNUKw0TLFYsPYJ07uGKD01hYa46do/lx41O44n8GDPqb05wpVkq?= =?us-ascii?Q?Gj80OJT6lS8u2FQImHaYynR2N/d3jDxdgtsg5DKCNaiUr5leF5liy6lBblCA?= =?us-ascii?Q?3+8483hyz/Ia4SV7tzbyjj/O2ijE6ynUos05AgTSYwVZz2qs5o+ClPtM1tE1?= =?us-ascii?Q?T8zXFbqZ6kN5NKDepMWV355TxGWuMk9Q+MfiOhOSoTWkH+bdv7R9BXHSzohO?= =?us-ascii?Q?MB86l7l3aDQaqZepocO/XeUmmAOpIoKmcfofmHb2Okua88RgCAGg8qKJnS+I?= =?us-ascii?Q?KSBuQwNCd6K0dDnzfo99yAfVLUJLsUCvlpC/dLojAH7gzZtjpWHzrY5A4lEH?= =?us-ascii?Q?JHcTEKBzEEGffUOV4Z+5nxIG8DiO6S0qbN8m0DXwD+XMJbYyoeSwnvE33Rqa?= =?us-ascii?Q?8oz/DdIu0xO7CJpZnYHVGprHeNMvNrEPHEVT50o0pyJDSbeIe8IRG7XRttUY?= =?us-ascii?Q?tyJs0R27ljsgaGJr8jbVWvT8C02BcGAmk/dmzy9bd4OfZoSXg7iacTZTSkbk?= =?us-ascii?Q?v9boP6vrJO1ofH3+fckjBoRP+PghZwT97Lajs6Twu1PNioZRFHgPE+nyi7ph?= =?us-ascii?Q?qcrosSW3bGYQbdLRmFW0TZCzQV7baxAzUdC8pupxocjSb5k946i/qwSHhJkf?= =?us-ascii?Q?DnNZ6apcyHTIPo6yOp2lJVCcBgGR3BsTkcjoamYcX/ch3Z1aBNHtVI7CLToc?= =?us-ascii?Q?3z+hjTtRvh0g/mLErvi6e7kOIISfNxUi9VgwmxBivxEZEDj6OluBFSb9fNJV?= =?us-ascii?Q?IOBvl2IPX6v5O2XK3M8fBk6x35+vDUZM+zlrNUui3pnCZWi/3nwdo0ZB00rx?= =?us-ascii?Q?xHZt3DhhX7zI2VMB5lbttDFu4g9MMa+qhcdOhcBGvGHOn6dT+GjzCe5vLXg+?= =?us-ascii?Q?Ntkgy0IfVBi45ztweMt0akUYn5PMkNSxOOrEZfcnGuRCj4/otEy+6mvvE7W0?= =?us-ascii?Q?mcdMiQeweFJGI4UNoJgOdG7vDftjPg/rBYBZkpvw+5eQV06fOn4D3iVoMcWO?= =?us-ascii?Q?Qg=3D=3D?= X-MS-Exchange-AntiSpam-ExternalHop-MessageData-ChunkCount: 1 X-MS-Exchange-AntiSpam-ExternalHop-MessageData-0: go+ddrDH4OHi3cp1dBTwyyx+sfJ71MjPumumc07IoK3WJYzSavLk6skhQG8QRLNMd60XveXPSGVI/jGLS7RKetioDlkevpaLmUyPidfb1TSImxmIB73BKnRRTkTCIWzo9HmgBQNtuhVwqlGJP1RsDA0zweSCC1UYRFXwP27YZPs9A4saZft6y0K4Ehhf7to81SukqkooUPGXA4MU+6cyDGbJgoyGbcpueNOg0l0CUlFIxOx1NLa01iTkAIdvAa8Ri5S/xaONNVcAX0CrA8BFAPWpUP5caBe69LzV97X8A249OgQaHhG2Br7u77uUY5a74efH47DjzyOSiUmnSTfw7Pz4Ph697NK4CTeRpVVf80nkR0+DU56sO8a50L8oyvSuQcKKvwMZjmWM16z8a84Aqy3bBHpnfQSrbXZBhj38U7NBmUluk357QG7DQCW8wniOINHfwxNWUKbL1leMpY24HwaasTIz3kGsCQytA2TjpUFt3LzeaqQksZ+p49RXQcvrsuguX66xgPSU4+hg12dybNppiHzS0NSMcIHDN4WndjBwDu2MU2McK9UH0yn5znN4czHccUBjqZjIXTq53YJVLhw+UEyl4THCzP4VNDNy6Ag= X-OriginatorOrg: oracle.com X-MS-Exchange-CrossTenant-Network-Message-Id: 23acc964-55fa-4368-7870-08dc7669866e X-MS-Exchange-CrossTenant-AuthSource: MW4PR10MB6608.namprd10.prod.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-OriginalArrivalTime: 17 May 2024 12:04:37.9549 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 4e2c6054-71cb-48f1-bd6c-3a9705aca71b X-MS-Exchange-CrossTenant-MailboxType: HOSTED X-MS-Exchange-CrossTenant-UserPrincipalName: xlJms1LNi/ykEZNBsavVnRcKaU3sNkcsH0tOgCgO49EPPdLMYTXewuF+FTN4GDQOaP7OVhVK7nGWCiUnsJxtfg== X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6PR10MB4186 X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1039,Hydra:6.0.650,FMLib:17.11.176.26 definitions=2024-05-17_03,2024-05-17_03,2023-05-22_02 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 mlxlogscore=738 mlxscore=0 spamscore=0 bulkscore=0 phishscore=0 malwarescore=0 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2405010000 definitions=main-2405170097 X-Proofpoint-GUID: J5h5rSoFGyUgvaX0ZLqsn7SxLvg518EX X-Proofpoint-ORIG-GUID: J5h5rSoFGyUgvaX0ZLqsn7SxLvg518EX X-Spam-Status: No, score=-5.9 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_MSPIKE_H4,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_NONE,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: On 14 May 2024, Nick Alcock told this: > Hopefully this library is no longer quite so much a "you have to look > in the source to understand anything" library. > > No semantic changes, though some functions have been moved around for > clarity. > > include/ > ctf-api.h: Add comments. This is now pushed, along with the previous series I posted a couple of weeks ago fixing various small bugs and one big error-path leak (of course I spotted the missing * in the changelog only a second too late). (I've also started signing my commits: as Jon Wakely suggested recently, I'm using the key I push to Sourceware with to do so.)