Fix duplicate C declaration warnings

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 <[email protected]>

---

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

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

Documentation/gpu/drm-kms.rst +0 -6

index 13d3627d8bc0..a4145f391e43 100644
@@ -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
 ==============
 

Signature · 1 line

2.44.0

Quoted 3 lines · Amogh Cheluvaraj

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 [email protected].

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.

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.

Quoted 5 lines

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