Re: [PATCH bpf-next v1 1/2] docs: fix sphinx warnings for cpumap

[David Vernet <void@manifault.com>]

On Tue, Nov 22, 2022 at 10:37:37AM +0000, mtahhan@redhat.com wrote:
> From: Maryam Tahhan <mtahhan@redhat.com>
> 
> Sphinx version >=3.3 warns about duplicate function delcarations in the

s/delcarations/declarations

> CPUMAP documentation. This is because the function name is the same for
> Kernel and Userspace BPF progs but the parameters and return types
> they take is what differs. This patch moves from using the ``c:function::``
> directive to using the ``code-block:: c`` directive. The patches also fix
> the indentation for the text associated with the "new" code block delcarations.
> 
> Signed-off-by: Maryam Tahhan <mtahhan@redhat.com>

LGTM, just left one optionl nit below. Thanks for fixing this up.

Acked-by: David Vernet <void@manifault.com>

> ---
>  Documentation/bpf/map_cpumap.rst | 48 ++++++++++++++++++++------------
>  1 file changed, 30 insertions(+), 18 deletions(-)
> 
> diff --git a/Documentation/bpf/map_cpumap.rst b/Documentation/bpf/map_cpumap.rst
> index 61a797a86342..e8d9f7abf26a 100644
> --- a/Documentation/bpf/map_cpumap.rst
> +++ b/Documentation/bpf/map_cpumap.rst
> @@ -30,15 +30,18 @@ Usage
>  
>  Kernel BPF
>  ----------
> -.. c:function::
> +bpf_redirect_map()
> +^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
>       long bpf_redirect_map(struct bpf_map *map, u32 key, u64 flags)
>  
> - Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
> - For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.
> +Redirect the packet to the endpoint referenced by ``map`` at index ``key``.
> +For ``BPF_MAP_TYPE_CPUMAP`` this map contains references to CPUs.
>  
> - The lower two bits of ``flags`` are used as the return code if the map lookup
> - fails. This is so that the return value can be one of the XDP program return
> - codes up to ``XDP_TX``, as chosen by the caller.
> +The lower two bits of ``flags`` are used as the return code if the map lookup
> +fails. This is so that the return value can be one of the XDP program return
> +codes up to ``XDP_TX``, as chosen by the caller.
>  
>  Userspace
>  ---------

Feel free to ignore as this isn't really relevant to your change, but
while you're here would you mind please fixing this up as well:

s/Userspace/User space

> @@ -47,12 +50,15 @@ Userspace
>      from an eBPF program. Trying to call these functions from a kernel eBPF
>      program will result in the program failing to load and a verifier warning.
>  
> -.. c:function::
> +bpf_map_update_elem()
> +^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
>      int bpf_map_update_elem(int fd, const void *key, const void *value, __u64 flags);
>  
> - CPU entries can be added or updated using the ``bpf_map_update_elem()``
> - helper. This helper replaces existing elements atomically. The ``value`` parameter
> - can be ``struct bpf_cpumap_val``.
> +CPU entries can be added or updated using the ``bpf_map_update_elem()``
> +helper. This helper replaces existing elements atomically. The ``value`` parameter
> +can be ``struct bpf_cpumap_val``.
>  
>   .. code-block:: c
>  
> @@ -64,23 +70,29 @@ Userspace
>          } bpf_prog;
>      };
>  
> - The flags argument can be one of the following:
> +The flags argument can be one of the following:
>    - BPF_ANY: Create a new element or update an existing element.
>    - BPF_NOEXIST: Create a new element only if it did not exist.
>    - BPF_EXIST: Update an existing element.
>  
> -.. c:function::
> +bpf_map_lookup_elem()
> +^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
> +
>      int bpf_map_lookup_elem(int fd, const void *key, void *value);
>  
> - CPU entries can be retrieved using the ``bpf_map_lookup_elem()``
> - helper.
> +CPU entries can be retrieved using the ``bpf_map_lookup_elem()``
> +helper.
> +
> +bpf_map_delete_elem()
> +^^^^^^^^^^^^^^^^^^^^^
> +.. code-block:: c
>  
> -.. c:function::
>      int bpf_map_delete_elem(int fd, const void *key);
>  
> - CPU entries can be deleted using the ``bpf_map_delete_elem()``
> - helper. This helper will return 0 on success, or negative error in case of
> - failure.
> +CPU entries can be deleted using the ``bpf_map_delete_elem()``
> +helper. This helper will return 0 on success, or negative error in case of
> +failure.
>  
>  Examples
>  ========
> -- 
> 2.34.1
>