From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.3 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, NICE_REPLY_A,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2F4A1C433ED for ; Thu, 8 Apr 2021 11:28:33 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id E463961105 for ; Thu, 8 Apr 2021 11:28:32 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org E463961105 Authentication-Results: mail.kernel.org; dmarc=fail (p=quarantine dis=none) header.from=suse.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from list by lists.xenproject.org with outflank-mailman.107190.204899 (Exim 4.92) (envelope-from ) id 1lUSpb-0006dw-ML; Thu, 08 Apr 2021 11:28:15 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 107190.204899; Thu, 08 Apr 2021 11:28:15 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lUSpb-0006dp-Ig; Thu, 08 Apr 2021 11:28:15 +0000 Received: by outflank-mailman (input) for mailman id 107190; Thu, 08 Apr 2021 11:28:14 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1lUSpa-0006dk-Qf for xen-devel@lists.xenproject.org; Thu, 08 Apr 2021 11:28:14 +0000 Received: from mx2.suse.de (unknown [195.135.220.15]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 9aeb4c76-c621-4dab-bdb3-9fb60d343b98; Thu, 08 Apr 2021 11:28:13 +0000 (UTC) Received: from relay2.suse.de (unknown [195.135.221.27]) by mx2.suse.de (Postfix) with ESMTP id 767E8B138; Thu, 8 Apr 2021 11:28:12 +0000 (UTC) X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: 9aeb4c76-c621-4dab-bdb3-9fb60d343b98 X-Virus-Scanned: by amavisd-new at test-mx.suse.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=susede1; t=1617881292; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=kawX5P+Vt+0SGErESCEqU7jbVFZd1jUoRyWpe1E/zEY=; b=WlmnN7EMu5xny0X0H0ZsCCIE3gBAiWpm3XbZW7ImFzpnXbttg/HFKcSGMBfI/FPPJ5p6Ej +8fmHAgoO9naHI8PI2nCaKhXP1dyaig9F2FovySQJDrRDT5hcgQieQqcbTObe+aunpbT+j VVweX5bDU64G9KFk76bmi8aSLKYLJCM= Subject: Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h To: Luca Fancellu Cc: Bertrand Marquis , wei.chen@arm.com, Andrew Cooper , George Dunlap , Ian Jackson , Julien Grall , Wei Liu , xen-devel@lists.xenproject.org, Stefano Stabellini References: <20210406103603.8530-1-luca.fancellu@arm.com> <20210406103603.8530-4-luca.fancellu@arm.com> <073e28bc-ad94-429d-6384-744864d12b57@suse.com> <5cad4ffb-44ec-4cde-f5bb-f59dc3ca59ca@suse.com> From: Jan Beulich Message-ID: <452286e1-8574-0501-a864-73ef1ff072bb@suse.com> Date: Thu, 8 Apr 2021 13:28:11 +0200 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.9.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit On 08.04.2021 13:02, Luca Fancellu wrote: > > >> On 7 Apr 2021, at 22:26, Stefano Stabellini wrote: >> >> On Wed, 7 Apr 2021, Jan Beulich wrote: >>> On 07.04.2021 10:42, Luca Fancellu wrote: >>>> Just to be sure that we are in the same page, are you suggesting to modify the name >>>> In this way? >>>> >>>> struct gnttab_cache_flush { >>>> - union { >>>> + union xen_gnttab_cache_flush_a { >>>> uint64_t dev_bus_addr; >>>> grant_ref_t ref; >>>> } a; >>>> >>>> Following this kind of pattern: xen__ ? >>> >>> While in general I would be fine with this scheme, for field names like >>> "a" or "u" it doesn't fit well imo. >> >> "a" is a bad name anyway, even for the member. We can take the >> opportunity to find a better name. Almost anything would be better than >> "a". Maybe "refaddr"? >> >> >>> I'm also unconvinced this would be >>> scalable to the case where there's further struct/union nesting. >> >> How many of these instances of multilevel nesting do we have? Luca might >> know. Probably not many? They could be special-cased. > > There are not many multilevel nesting instances of anonymous struct/union and the maximum level of nesting I found in the public headers is 2: > > union { > union/struct { > … > } > } > > I also see that in the majority of cases the unions have not meaningful names like “a” or “u” as member name, instead struct names are fine, > It could be fine to keep the meaningful name the same for the struct type name and use the pattern for the non-meaningful ones as long > as the names doesn’t create compilation errors? > > Example: > > struct upper_level { > union { > struct { > > } meaningful_name1; > struct { > > } meaningful_name2; > } u; > }; > > becomes: > > struct upper_level { > union upper_level_u { > struct meaningful_name1 { > > } meaningful_name1; > struct meaningful_name2 { > > } meaningful_name2; > } u; > }; As you say - as long as there aren't any compilation issues. Two top level struct-s could have identically named struct/union fields without tag, in which case your approach outlined above will fail. And even if there was no such case right now, the case would need to be covered in whatever naming model was to be used (except, of course, the one without any names). Jan