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

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Wed,  4 Jun 2025 08:36:44 -0600
Jonathan Corbet <corbet@lwn.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@lwn.net>

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.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