Received-SPF: pass (google.com: domain of linux-kernel+bounces-118352-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:40f1:3f00::1 as permitted sender) client-ip=2604:1380:40f1:3f00::1;
Message-ID: <f735ce0b-db1e-49bc-86ac-b5ab8e4aec31@gmail.com>
Date: Tue, 26 Mar 2024 13:05:39 +0900
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
To: amogh.linux.kernel.dev@gmail.com
Cc: airlied@gmail.com, corbet@lwn.net, daniel@ffwll.ch,
 dri-devel@lists.freedesktop.org, javier.carrasco.cruz@gmail.com,
 linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
 maarten.lankhorst@linux.intel.com, mripard@kernel.org,
 skhan@linuxfoundation.org, tzimmermann@suse.de, willy@infradead.org,
 Mauro Carvalho Chehab <mchehab@kernel.org>
References: <287eb3f74e4c31adb065668ff49c8e1577388227.camel@gmail.com>
Subject: Re: [PATCH v2] Fix duplicate C declaration warnings
Content-Language: en-US
From: Akira Yokosawa <akiyks@gmail.com>
In-Reply-To: <287eb3f74e4c31adb065668ff49c8e1577388227.camel@gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

Hello.
Let me chime in.

On Mon, 25 Mar 2024 13:03:10 +0530, Amogh Cheluvaraj wrote:
[...]
> After further introspection of the file drivers/gpu/drm/drm_fourcc.c, I
> found that the warning is caused by having the same name for both the
> struct and the function as in "const struct drm_format_info
> *drm_format_info(u32 format)". This is an issue found using the latest
> version of Sphinx as reported by Akira Yokosawa in message id
> 564cbd05-8788-9223-1ecc-59e7fc41b46a@gmail.com.

That message of mine just pointed out that the Sphinx bug of false
duplicate C declaration warning first reported by Mauro (+CC'd) at:
https://github.com/sphinx-doc/sphinx/issues/8241 --
"C domain issues when building the Linux Kernel documentation".
It had not been resolved despite Mauro's recognition of the issue at the
time.

It was closed without fixing the bug but delegate the issue to an earlier
one of the same nature at: https://github.com/sphinx-doc/sphinx/issues/7819 --
"C, distinguish between ordinary identifiers and tag names", which was
opened on Jun 12, 2020 and has not been resolved.  (almost 4 years ago!)

There is two pull requests attempting to resolve the issue at:
https://github.com/sphinx-doc/sphinx/pull/8313 --
"C, distinguish between tag names and ordinary names" and
https://github.com/sphinx-doc/sphinx/pull/8929 --
"Intersphinx delegation to domains".
PR #8313 needs #8929 as its prerequisite.

Unfortunately, both PRs are still open as well as the issue #7819.
Honestly speaking, I don't have any idea what prevents those pulls,
give or take the need of rebasing with conflict resolution.

>                                                  So by changing the
> function name to something like "query_drm_format_info(u32 format)" is
> a possible fix. Question is what should I rename this function to, that
> aligns with the coding standards? Also suggest a new function name for
> "drm_modeset_lock" that causes the second warning.

So, I would rather not rename valid identifiers for the sake of working
around a bug of Sphinx.  Rather, I'd appreciate if you'd send a message
encouraging Sphinx devs to resolve the issue sooner rather than later.

        Thanks, Akira