| Message ID | 20240323163148.23497-1-amogh.linux.kernel.dev@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] Fix duplicate C declaration warnings | expand |
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 > >
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.
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
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.
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 ==============
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(-)