linux-kernel - Re: [PATCH v2 2/3] docs: automarkup: Mark up undocumented entities too

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250604165744.68d98975@sal.lan>
Date: Wed, 4 Jun 2025 16:57:44 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, "
 Nícolas F. R. A. Prado" <nfraprado@...labora.com>
Subject: Re: [PATCH v2 2/3] docs: automarkup: Mark up undocumented entities
 too

Em Wed,  4 Jun 2025 08:36:44 -0600
Jonathan Corbet <corbet@....net> escreveu:

> The automarkup code generates markup and a cross-reference link for
> functions, structs, etc. for which it finds kerneldoc documentation.
> Undocumented entities are left untouched; that creates an inconsistent
> reading experience and has caused some writers to go to extra measures to
> cause the markup to happen.
> 
> Mark up detected C entities regardless of whether they are documented.
> 
> Signed-off-by: Jonathan Corbet <corbet@....net>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>

> ---
> v2: Split out the CSS changes into a separate patch
> 
>  Documentation/sphinx/automarkup.py | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
> index 7828aeac92e7..e67eb8e19c22 100644
> --- a/Documentation/sphinx/automarkup.py
> +++ b/Documentation/sphinx/automarkup.py
> @@ -235,8 +235,13 @@ def add_and_resolve_xref(app, docname, domain, reftype, target, contnode=None):
>  
>      if xref:
>          return xref
> -
> -    return None
> +    #
> +    # We didn't find the xref; if a container node was supplied,
> +    # mark it as a broken xref
> +    #
> +    if contnode:
> +        contnode.set_class("broken_xref")
> +    return contnode
>  
>  #
>  # Variant of markup_abi_ref() that warns whan a reference is not found