Subject: Re: [PATCH net-next 1/6] docs: add more netlink docs (incl. spec docs)

From: Jakub Kicinski <[email-masked]>
Date: Thu, 29 Sep 2022 08:47:15 -0700

On Thu, 29 Sep 2022 17:11:45 +0200 Guillaume Nault wrote:
> Maybe we can make this more explicit.
> Something like:
> 
> -Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
> +Users shouldn't have to use ``NLM_F_ECHO`` to get a handle on the created
> +object.
> 
> (or keep both sentences, I feel they fit well together).
> 
> Then maybe explain in the next section why support for NLM_F_ECHO is
> desirable anyway:
> 
>  Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
> -to take effect.
> +to take effect. This is usefull for programs that need precise feedback from
> + the kernel (for example for logging purpose).

Folded it a little bit:

diff --git a/Documentation/core-api/netlink.rst b/Documentation/core-api/netlink.rst
index 2a97f765d0d2..7b98dd48a6af 100644
--- a/Documentation/core-api/netlink.rst
+++ b/Documentation/core-api/netlink.rst
@@ -37,15 +37,15 @@ added whether it replies with a full message or only an ACK is uAPI and
 cannot be changed. It's better to err on the side of replying.
 
 Specifically NEW and ADD commands should reply with information identifying
-the created object such as the allocated object's ID.
-
-Having to rely on ``NLM_F_ECHO`` is a hack, not a valid design.
+the created object such as the allocated object's ID (without having to
+resort to using ``NLM_F_ECHO``).
 
 NLM_F_ECHO
 ----------
 
 Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
-to take effect.
+to take effect.  This is useful for programs that need precise feedback
+from the kernel (for example for logging purposes).
 
 Support dump consistency
 ------------------------