[PATCH v2] Fix duplicate C declaration warnings

[PATCH v2] Fix duplicate C declaration warnings

[Amogh Cheluvaraj]

Fix duplicate C declaration warnings at
Documentation/gpu/drm-kms.rst that was found by
compiling htmldocs

/home/amogh/Linux_Kernel_Workspace/linux-next/Documentation/gpu/drm-
kms:360: ./drivers/gpu/drm/drm_fourcc.c:344: WARNING: Duplicate C
declaration, also defined at gpu/drm-kms:39.
Declaration is '.. c:function:: const struct drm_format_info *
drm_format_info (u32 format)'.
/home/amogh/Linux_Kernel_Workspace/linux-next/Documentation/gpu/drm-
kms:461: ./drivers/gpu/drm/drm_modeset_lock.c:392: WARNING: Duplicate C
declaration, also defined at gpu/drm-kms:49.
Declaration is '.. c:function:: int drm_modeset_lock (struct
drm_modeset_lock *lock, struct drm_modeset_acquire_ctx *ctx)'.

Signed-off-by: Amogh Cheluvaraj <amogh.linux.kernel.dev@gmail.com>
---

changes in v2
- add warnings found after compilation
- fix grammar in commit description

---
 Documentation/gpu/drm-kms.rst | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 13d3627d8bc0..a4145f391e43 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -357,9 +357,6 @@ Format Functions Reference
 .. kernel-doc:: include/drm/drm_fourcc.h
    :internal:
 
-.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
-   :export:
-
 .. _kms_dumb_buffer_objects:
 
 Dumb Buffer Objects
@@ -458,9 +455,6 @@ KMS Locking
 .. kernel-doc:: include/drm/drm_modeset_lock.h
    :internal:
 
-.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
-   :export:
-
 KMS Properties
 ==============
 
-- 
2.44.0

Re: [PATCH v2] Fix duplicate C declaration warnings

[Matthew Wilcox]

On Sat, Mar 23, 2024 at 10:01:47PM +0530, Amogh Cheluvaraj wrote:
> Fix duplicate C declaration warnings at
> Documentation/gpu/drm-kms.rst that was found by
> compiling htmldocs

I'm sure this removes the warning, but it removes all kernel-doc
which exists in drivers/gpu/drm/drm_fourcc.c.  Isn't there a more
granular fix than this?

> /home/amogh/Linux_Kernel_Workspace/linux-next/Documentation/gpu/drm-
> kms:360: ./drivers/gpu/drm/drm_fourcc.c:344: WARNING: Duplicate C
> declaration, also defined at gpu/drm-kms:39.
> Declaration is '.. c:function:: const struct drm_format_info *
> drm_format_info (u32 format)'.
> /home/amogh/Linux_Kernel_Workspace/linux-next/Documentation/gpu/drm-
> kms:461: ./drivers/gpu/drm/drm_modeset_lock.c:392: WARNING: Duplicate C
> declaration, also defined at gpu/drm-kms:49.
> Declaration is '.. c:function:: int drm_modeset_lock (struct
> drm_modeset_lock *lock, struct drm_modeset_acquire_ctx *ctx)'.
> 
> Signed-off-by: Amogh Cheluvaraj <amogh.linux.kernel.dev@gmail.com>
> ---
> 
> changes in v2
> - add warnings found after compilation
> - fix grammar in commit description
> 
> ---
>  Documentation/gpu/drm-kms.rst | 6 ------
>  1 file changed, 6 deletions(-)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 13d3627d8bc0..a4145f391e43 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -357,9 +357,6 @@ Format Functions Reference
>  .. kernel-doc:: include/drm/drm_fourcc.h
>     :internal:
>  
> -.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
> -   :export:
> -
>  .. _kms_dumb_buffer_objects:
>  
>  Dumb Buffer Objects
> @@ -458,9 +455,6 @@ KMS Locking
>  .. kernel-doc:: include/drm/drm_modeset_lock.h
>     :internal:
>  
> -.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
> -   :export:
> -
>  KMS Properties
>  ==============
>  
> -- 
> 2.44.0
> 
> 

Re: [PATCH v2] Fix duplicate C declaration warnings

[Amogh]

On Sat, 2024-03-23 at 20:43 +0000, Matthew Wilcox wrote:
> On Sat, Mar 23, 2024 at 10:01:47PM +0530, Amogh Cheluvaraj wrote:
> > Fix duplicate C declaration warnings at
> > Documentation/gpu/drm-kms.rst that was found by
> > compiling htmldocs
> 
> I'm sure this removes the warning, but it removes all kernel-doc
> which exists in drivers/gpu/drm/drm_fourcc.c.  Isn't there a more
> granular fix than this?
> 

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. 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.

Re: [PATCH v2] Fix duplicate C declaration warnings

[Akira Yokosawa]

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

Re: [PATCH v2] Fix duplicate C declaration warnings

[Donald Hunter]

Akira Yokosawa <akiyks@gmail.com> writes:
>
> 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

Agreed, we should try and get the bug resolved in Sphinx. This same
issue came up in relation to this PR that I am working on so hopefully
we can work together to get fixes merged upstream:

https://github.com/sphinx-doc/sphinx/pull/12162

Thanks,
Donald.