On Mon, 24 Apr 2023 14:28:00 -0700 Jakub Kicinski <kuba@xxxxxxxxxx> wrote: > 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 Internal Kernel API's are not stable. So documentation is only the auto generated kernel docs. There is an effort to cover netlink API's with YAML. Bridge could/should be part of that. > - 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 Yes, but that is what distributions want. > - 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. The in-kernel documents usually only cover the architecture and motivation. What/why/how... Not the user visible public API's.
