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

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ