[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h
- To: Jan Beulich <jbeulich@xxxxxxxx>
- From: Bertrand Marquis <Bertrand.Marquis@xxxxxxx>
- Date: Wed, 7 Apr 2021 16:07:41 +0000
- Accept-language: en-GB, en-US
- Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass header.d=arm.com; arc=none
- 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-SenderADCheck; bh=amgov6jNIxbtMFAnjEVxzR9nnPjqcmUb+nfviCse9VM=; b=JoWHKH94Vw8/18C76+QpBR1rMpT+pyA/Z69CMvQC+dgi8Z5zACDoYcpOa0RUNy6OgXrvONqB0/TvohCxm2H/vuswiXpGyNt6phh1J5SzAPfgVD0WCesd5zp9DqfU0255oDF7nhuzRpajeKIKS6wzB3YmtyNHxfzGsu3/PSZiPOOR2MICEDhgDa4XWnBu/6SPmjzKUAK2eSgy5bzq58CSX+27gLFvU1U0Ns/PNPA4k690drPkA+oVZEwdd1tV2vEOO767jbBWCNiYntj3HodiQ6gue/FiTmE4thjhJZ8dECXM9Vdlhfs5cnR3uEXFJ9SUPCapg5TeB+tQApsomX+OzQ==
- Arc-seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=h0zoPeOcJ5xnTLYGNXblnSC/jv1YrZjeQa6PQeNVmD8t5fOqams3WfBWYxk/6B0oUVEK+p/btg2hHyB0ri3NaiX8s6eweFYf/1MlZ1SAzG7RkZ1Q1iTl55/PcptFNyJHUqUj5LGE39Woj+gVwPm6CirvlvzFQ1f4lpo4tGMzVelbwySPi3YK6t3b6oJ79+5uzo4AH9znQSsFhWLUhA8A4QL0SeMOoopAxTNy8zBGZTpI+wAE9kEkHXPVXCd2TCRIH/hmerniYhdwcLWUpFzaZgXWuZSrUdU+BHWfrD3NGvHQGnpaq5P7sibUb3S0g0NTG5cipJs9095la7//gJeIlA==
- Authentication-results-original: suse.com; dkim=none (message not signed) header.d=none;suse.com; dmarc=none action=none header.from=arm.com;
- Cc: Luca Fancellu <Luca.Fancellu@xxxxxxx>, Julien Grall <julien@xxxxxxx>, "xen-devel@xxxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxxx>, Wei Chen <Wei.Chen@xxxxxxx>, Andrew Cooper <andrew.cooper3@xxxxxxxxxx>, George Dunlap <george.dunlap@xxxxxxxxxx>, Stefano Stabellini <sstabellini@xxxxxxxxxx>, Wei Liu <wl@xxxxxxx>, Ian Jackson <iwj@xxxxxxxxxxxxxx>
- Delivery-date: Wed, 07 Apr 2021 16:08:05 +0000
- List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
- Nodisclaimer: true
- Original-authentication-results: suse.com; dkim=none (message not signed) header.d=none;suse.com; dmarc=none action=none header.from=arm.com;
- Thread-index: AQHXKtDW6d1uIaHDNEirYTRFGCHHX6qpCgoAgAABvgCAACFYgIAAAteAgAAHEwCAAAOYAA==
- Thread-topic: [PATCH 3/3] docs/doxygen: doxygen documentation for grant_table.h
Hi,
> On 7 Apr 2021, at 16:54, Jan Beulich <jbeulich@xxxxxxxx> wrote:
>
> On 07.04.2021 17:29, Bertrand Marquis wrote:
>>> On 7 Apr 2021, at 16:19, Ian Jackson <iwj@xxxxxxxxxxxxxx> wrote:
>>>
>>> Luca Fancellu writes ("Re: [PATCH 3/3] docs/doxygen: doxygen documentation
>>> for grant_table.h"):
>>>> The problem is that Doxygen can’t generate proper documentation for
>>>> anonymous union/structure, it ends up with warning and/or producing wrong
>>>> documentation like
>>>> changing names or giving field description to the wrong field.
>>>
>>> This does not seem like it would be an impossibly hard feature to add
>>> to doxygen.
>>
>> Modifying doxygen is not really in our planned efforts and if someone does
>> it that would put an hard constraint on the version of doxygen possible to
>> use.
>>
>> But is adding names to anonymous elements really an issue here ?
>
> It's clutter in the code base, making things harder to read (even if
> just slightly). It's certainly odd to make such source changes just
> for a doc tool. If changing doxygen is not an option for you, how
> about pre-processing the header and inserting the names the tool
> wants, before handing the result as input to it?
Introducing a new tool or find a pre-processing solution is for sure possible
but will be more complex and less error prone.
Also as said in my mail to Julien, passing this issue of anonymous entries now
might just push the problem as we might have to solve it later if we want to
become
MISRA compliant (which is also something we are looking in FuSa).
Regards
Bertrand
>
> Jan
>
|
