Re: [PATCH] workaround for Sphinx false positive preventing index

[Jani Nikula <jani.nikula@linux.intel.com>]

On Fri, 27 Jun 2025, Kevin Paul Reddy Janagari <kevinpaul468@gmail.com> wrote:
> Functions drm_format_info, drm_modeset_lock, drm_ioctl_flags are not being
> indexed in the documentation because there are structs with the same name 
> and sphinx is only indexing one of them, Added them to namespaces as a
> workaround for suppressing the warnings and indexing the functions

I think there's a Sphinx bug about this that should be referenced.

Cc: Mauro

> Signed-off-by: Kevin Paul Reddy Janagari <kevinpaul468@gmail.com>
> ---
>  Documentation/gpu/drm-kms.rst  | 2 ++
>  Documentation/gpu/drm-uapi.rst | 1 +
>  2 files changed, 3 insertions(+)
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index abfe220764e1..da865ba1c014 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -357,6 +357,7 @@ Format Functions Reference
>  .. kernel-doc:: include/drm/drm_fourcc.h
>     :internal:
>  
> +.. c:namespace:: gpu_drm_fourcc

I think using c:namespace-push and c:namespace-pop is the better
option. Otherwise c:namespace will be in effect until the end of the rst
file or next c:namespace.

I'm not quite sure what the namespace names should be, but for
referencing anything the names here are pretty bad
e.g. gpu_drm_fourcc.drm_format_info.

As a workaround this does hide the worst fallout, but it's not even
generic enough to handle structs and functions with the same name in the
same file. I'm not sure if there are such cases, but I wouldn't be
surprised if there were.

A more generic (but also invasive) alternative would be to have
kernel-doc always put structs/unions in a namespace, say "type", so
they'd never conflict with functions. The automagic referencing in
kernel-doc could produce those references. The downside is that manual
references should include type.foo, and the produced html also contains
type.foo.

BR,
Jani.


>  .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c :export:
>  
> @@ -473,6 +474,7 @@ KMS Locking
>  .. kernel-doc:: include/drm/drm_modeset_lock.h
>     :internal:
>  
> +.. c:namespace:: gpu_drm_modeset_lock
>  .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
>     :export:
>  
> diff --git a/Documentation/gpu/drm-uapi.rst b/Documentation/gpu/drm-uapi.rst
> index 69f72e71a96e..37a2bc461326 100644
> --- a/Documentation/gpu/drm-uapi.rst
> +++ b/Documentation/gpu/drm-uapi.rst
> @@ -554,6 +554,7 @@ DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of
>  .. kernel-doc:: include/drm/drm_ioctl.h
>     :internal:
>  
> +.. c:namespace:: gpu_drm
>  .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c
>     :export:

-- 
Jani Nikula, Intel