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.
