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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <462a34d3027f22a65c129e2305c7aa4d4fda0e43@intel.com>
Date: Fri, 27 Jun 2025 12:00:07 +0300
From: Jani Nikula <jani.nikula@...ux.intel.com>
To: Kevin Paul Reddy Janagari <kevinpaul468@...il.com>, airlied@...il.com,
 simona@...ll.ch, maarten.lankhorst@...ux.intel.com, mripard@...nel.org,
 tzimmermann@...e.de, corbet@....net
Cc: dri-devel@...ts.freedesktop.org, linux-doc@...r.kernel.org,
 linux-kernel@...r.kernel.org, kevinpaul468@...il.com, Mauro Carvalho
 Chehab <mchehab+huawei@...nel.org>
Subject: Re: [PATCH] workaround for Sphinx false positive preventing index

On Fri, 27 Jun 2025, Kevin Paul Reddy Janagari <kevinpaul468@...il.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@...il.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