Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20221104123913.50610-1-bagasdotme@gmail.com>
In-Reply-To: <20221104123913.50610-1-bagasdotme@gmail.com>
From:   Andrii Nakryiko <andrii.nakryiko@gmail.com>
Date:   Fri, 4 Nov 2022 16:11:10 -0700
Message-ID: <CAEf4Bzau0QuBiNsXoMq_QRV+_MTyodQsvW7O2kbScgmVmbuXkQ@mail.gmail.com>
Subject: Re: [PATCH bpf-next] Documentation: bpf: escape underscore in BPF
 type name prefix
To:     Bagas Sanjaya <bagasdotme@gmail.com>
Cc:     bpf@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org, Alexei Starovoitov <ast@kernel.org>,
        Daniel Borkmann <daniel@iogearbox.net>,
        Andrii Nakryiko <andrii@kernel.org>,
        Martin KaFai Lau <martin.lau@linux.dev>,
        Song Liu <song@kernel.org>, Yonghong Song <yhs@fb.com>,
        John Fastabend <john.fastabend@gmail.com>,
        KP Singh <kpsingh@kernel.org>,
        Stanislav Fomichev <sdf@google.com>,
        Hao Luo <haoluo@google.com>, Jiri Olsa <jolsa@kernel.org>,
        Jonathan Corbet <corbet@lwn.net>,
        David Vernet <void@manifault.com>,
        Kumar Kartikeya Dwivedi <memxor@gmail.com>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Fri, Nov 4, 2022 at 5:39 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
>
> Sphinx reported unknown target warning:
>
> Documentation/bpf/bpf_design_QA.rst:329: WARNING: Unknown target name: "bpf".
>
> The warning is caused by BPF type name prefix ("bpf_") which is written
> without escaping the trailing underscore.
>
> Escape the underscore to fix the warning. While at it, wrap the
> containing paragraph in less than 80 characters.
>
> Fixes: 9805af8d8a5b17 ("bpf: Document UAPI details for special BPF types")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/bpf/bpf_design_QA.rst | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>

Applied, thanks. But would the other similar case be problematic?

$ rg 'bpf_\b'
bpf_design_QA.rst
329:NOTE: BPF subsystem specially reserves the 'bpf_' prefix for type names, in
331:avoid defining types with 'bpf_' prefix to not be broken in future
releases. In
333:with 'bpf_' prefix.

libbpf/libbpf_naming_convention.rst
12:following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``btf_dump_``,
59:described above should have ``libbpf_`` prefix, e.g.


> diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> index 4e4af398607b58..17e774d96c5e4b 100644
> --- a/Documentation/bpf/bpf_design_QA.rst
> +++ b/Documentation/bpf/bpf_design_QA.rst
> @@ -326,11 +326,11 @@ size, type, and alignment, or any other user visible API or ABI detail across
>  kernel releases. The users must adapt their BPF programs to the new changes and
>  update them to make sure their programs continue to work correctly.
>
> -NOTE: BPF subsystem specially reserves the 'bpf_' prefix for type names, in
> +NOTE: BPF subsystem specially reserves the 'bpf\_' prefix for type names, in
>  order to introduce more special fields in the future. Hence, user programs must
> -avoid defining types with 'bpf_' prefix to not be broken in future releases. In
> -other words, no backwards compatibility is guaranteed if one using a type in BTF
> -with 'bpf_' prefix.
> +avoid defining types with 'bpf\_' prefix to not be broken in future releases.
> +In other words, no backwards compatibility is guaranteed if one using a type
> +in BTF with 'bpf\_' prefix.
>
>  Q: What is the compatibility story for special BPF types in local kptrs?
>  ------------------------------------------------------------------------
>
> base-commit: f71b2f64177a199d5b1d2047e155d45fd98f564a
> --
> An old man doll... just what I always wanted! - Clara
>