Linux Ethernet Bridging - Apr 2023 - [Bridge] [Question] Any plan to write/update the bridge doc?

Hi,

Maybe someone already has asked. The only official Linux bridge document I
got is a very ancient wiki page[1] or the ip link man page[2][3]. As there are
many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
document about each parameter? The parameter showed in ip link page seems
a little brief.

I'd like to help do this work. But apparently neither my English nor my
understanding of the code is good enough. Anyway, if you want, I can help
write a draft version first and you (bridge maintainers) keep working on this.

[1] https://wiki.linuxfoundation.org/networking/bridge
[2] https://man7.org/linux/man-pages/man8/bridge.8.html
[3] https://man7.org/linux/man-pages/man8/ip-link.8.html

Thanks
Hangbin

On Mon, Apr 24, 2023 at 05:25:08PM +0800, Hangbin Liu
wrote:
> Hi,
> 
> Maybe someone already has asked. The only official Linux bridge document I
> got is a very ancient wiki page[1] or the ip link man page[2][3]. As there
are
> many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> document about each parameter? The parameter showed in ip link page seems
> a little brief.
I suggest improving the man pages instead of adding kernel
documentation. The man pages are the most up to date resource and
therefore the one users probably refer to the most. Also, it's already
quite annoying to patch both "ip-link" and "bridge" man
pages when
adding bridge port options. Adding a third document and making sure all
three resources are patched would be a nightmare...
> 
> I'd like to help do this work. But apparently neither my English nor my
> understanding of the code is good enough. Anyway, if you want, I can help
> write a draft version first and you (bridge maintainers) keep working on
this.
I can help reviewing man page patches if you want. I'm going to send
some soon. Will copy you.
> 
> [1] https://wiki.linuxfoundation.org/networking/bridge
> [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> [3] https://man7.org/linux/man-pages/man8/ip-link.8.html
> 
> Thanks
> Hangbin

On Mon, 24 Apr 2023 17:25:08 +0800 Hangbin Liu wrote:
> Maybe someone already has asked. The only official Linux bridge document I
> got is a very ancient wiki page[1] or the ip link man page[2][3]. As there
are
> many bridge stp/vlan/multicast paramegers. Should we add a detailed kernel
> document about each parameter? The parameter showed in ip link page seems
> a little brief.
> 
> I'd like to help do this work. But apparently neither my English nor my
> understanding of the code is good enough. Anyway, if you want, I can help
> write a draft version first and you (bridge maintainers) keep working on
this.
> 
> [1] https://wiki.linuxfoundation.org/networking/bridge
> [2] https://man7.org/linux/man-pages/man8/bridge.8.html
> [3] https://man7.org/linux/man-pages/man8/ip-link.8.html
Sounds like we have 2 votes for the CLI man pages but I'd like to
register a vote for in-kernel documentation.

I work at a large company so my perspective may differ but from what 
I see:

 - users who want to call the kernel API should not have to look at 
   the CLI's man
 - man pages use archaic and arcane markup, I'd like to know how many
   people actually know how it works and how many copy / paste / look;
   ReST is prevalent, simple and commonly understood
 - in-kernel docs are rendered on the web as soon as they hit linux-next
 - we can make sure documentation is provided with the kernel changes,
   in an ideal world it doesn't matter but in practice the CLI support
   may never happen (no to mention that iproute does not hold all CLI)

Obviously if Stephen and Ido prefer to document the bridge CLI that's
perfectly fine, it's their call :) For new sections of uAPI, however,
I personally find in-kernel docs superior.