Re: [RFC Draft PATCH net-next 0/1] Bridge doc update

On 9/20/23 12:19, Hangbin Liu wrote:

Hi Nikolay, Roopa,

Do you have any comments for this RFC?

Thanks
Hangbin
On Wed, Sep 13, 2023 at 05:28:52PM +0800, Hangbin Liu wrote:

quoted

Hi,

After a long busy period. I got time to check how to update the bridge doc.
Here is the previous discussion we made[1].

In this update. I plan to convert all the bridge description/comments to
the kernel headers. And add sphinx identifiers in the doc to show them
directly. At the same time, I wrote a script to convert the description
in kernel header file to iproute2 man doc. With this, there is no need
to maintain the doc in 2 places.

For the script. I use python docutils to read the rst comments. When dump
the man page. I do it manually to match the current ip link man page style.
I tried rst2man, but the generated man doc will break the current style.
If you have any other better way, please tell me.

[1] https://lore.kernel.org/netdev/5ddac447-c268-e559-a8dc-08ae3d124352@blackwall.org/ (local)


Hangbin Liu (1):
   Doc: update bridge doc

  Documentation/networking/bridge.rst |  85 ++++++++++--
  include/uapi/linux/if_bridge.h      |  24 ++++
  include/uapi/linux/if_link.h        | 194 ++++++++++++++++++++++++++++
  3 files changed, 293 insertions(+), 10 deletions(-)

-- 
2.41.0

Hi Hangbin,
I support all efforts to improve documentation, but I do share the same concerns that Stephen has already voiced. I don't think we should be generating the man page from the kernel docs, IMO it would be simpler
and easier for everyone to support both docs - one is for the user-space
iproute2 commands, the other could go into the kernel api details. All
attribute descriptions can still be added to headers, that would be very
valuable on its own. I prefer to have the freedom to change the docs format in any way, generating them from comments is kind of limiting.
The purpose of each document is different and it will be difficult
to combine them for a man page. It would be much easier for everyone
to add user-related command descriptions and examples in iproute2's documentation, and to add kernel-specific (or uapi) documentation to the
kernel doc. We can add references for each with a short description.
W.r.t the kernel doc topics covered, I think the list is a good start.

Thank you,
 Nik