diff mbox series

[bpf-next] Documentation: bpf: escape underscore in BPF type name prefix

Message ID 20221104123913.50610-1-bagasdotme@gmail.com
State New
Headers
Series [bpf-next] Documentation: bpf: escape underscore in BPF type name prefix |

Commit Message

Bagas Sanjaya Nov. 4, 2022, 12:39 p.m. UTC 
  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(-)


base-commit: f71b2f64177a199d5b1d2047e155d45fd98f564a

Comments

KP Singh Nov. 4, 2022, 1:16 p.m. UTC | #1 
On Fri, Nov 4, 2022 at 1:39 PM 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>

Acked-by: KP Singh <kpsingh@kernel.org>
David Vernet Nov. 4, 2022, 3:05 p.m. UTC | #2 
On Fri, Nov 04, 2022 at 07:39:14PM +0700, Bagas Sanjaya 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>

Acked-by: David Vernet <void@manifault.com>
Andrii Nakryiko Nov. 4, 2022, 11:11 p.m. UTC | #3 
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
>
patchwork-bot+netdevbpf@kernel.org Nov. 4, 2022, 11:20 p.m. UTC | #4 
Hello:

This patch was applied to bpf/bpf-next.git (master)
by Andrii Nakryiko <andrii@kernel.org>:

On Fri,  4 Nov 2022 19:39:14 +0700 you 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.
> 
> [...]

Here is the summary with links:
  - [bpf-next] Documentation: bpf: escape underscore in BPF type name prefix
    https://git.kernel.org/bpf/bpf-next/c/25906092edb4

You are awesome, thank you!
Akira Yokosawa Nov. 5, 2022, 12:05 a.m. UTC | #5 
Hi,

On Fri, 4 Nov 2022 16:11:10 -0700, Andrii Nakryiko wrote:
[...]
> 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.

Those other cases are all inside double back quotes and
construct "inline literal" strings. So they are fine.

Which means Bagas could have used the "inline literal" approach
instead.

Regards,
Akira
Bagas Sanjaya Nov. 5, 2022, 2:49 a.m. UTC | #6 
On 11/5/22 07:05, Akira Yokosawa wrote:
> Hi,
> 
> On Fri, 4 Nov 2022 16:11:10 -0700, Andrii Nakryiko wrote:
> [...]
>> 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.
> 
> Those other cases are all inside double back quotes and
> construct "inline literal" strings. So they are fine.
> 
> Which means Bagas could have used the "inline literal" approach
> instead.
> 

Ah! I was oversighted (not seeing these other cases). Should I convert
fixed 'bpf_' to inline literals?
diff mbox series

Patch

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?
 ------------------------------------------------------------------------