Re: [RFC PATCHv3 net-next 04/10] docs: bridge: Add kAPI/uAPI fields

From: Simon Horman <horms@kernel.org>
To: Hangbin Liu <liuhangbin@gmail.com>
Cc: netdev@vger.kernel.org, "David S . Miller" <davem@davemloft.net>,
	David Ahern <dsahern@kernel.org>,
	Eric Dumazet <edumazet@google.com>,
	Jakub Kicinski <kuba@kernel.org>, Paolo Abeni <pabeni@redhat.com>,
	Ido Schimmel <idosch@idosch.org>,
	Nikolay Aleksandrov <razor@blackwall.org>,
	Roopa Prabhu <roopa@nvidia.com>,
	Stephen Hemminger <stephen@networkplumber.org>,
	Florian Westphal <fw@strlen.de>, Andrew Lunn <andrew@lunn.ch>,
	Florian Fainelli <f.fainelli@gmail.com>,
	Vladimir Oltean <olteanv@gmail.com>,
	Jiri Pirko <jiri@resnulli.us>
Subject: Re: [RFC PATCHv3 net-next 04/10] docs: bridge: Add kAPI/uAPI fields
Date: Sat, 11 Nov 2023 19:07:33 +0000	[thread overview]
Message-ID: <20231111190733.GD705326@kernel.org> (raw)
In-Reply-To: <20231110101548.1900519-5-liuhangbin@gmail.com>

On Fri, Nov 10, 2023 at 06:15:41PM +0800, Hangbin Liu wrote:
> The current bridge kernel doc is too old. It only pointed to the
> linuxfoundation wiki page which lacks of the new features.
> 
> Here let's start the new bridge document and put all the bridge info
> so new developers and users could catch up the last bridge status soon.
> 
> First add kAPI/uAPI and FAQ fields. These 2 fileds are only examples and
> more APIs need to be added in future.
> 
> Signed-off-by: Hangbin Liu <liuhangbin@gmail.com>
> ---
>  Documentation/networking/bridge.rst | 83 +++++++++++++++++++++++++----
>  1 file changed, 73 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/networking/bridge.rst b/Documentation/networking/bridge.rst
> index c859f3c1636e..d06c51960f45 100644
> --- a/Documentation/networking/bridge.rst
> +++ b/Documentation/networking/bridge.rst
> @@ -4,18 +4,81 @@
>  Ethernet Bridging
>  =================
>  
> -In order to use the Ethernet bridging functionality, you'll need the
> -userspace tools.
> +Introduction
> +============
>  
> -Documentation for Linux bridging is on:
> -   https://wiki.linuxfoundation.org/networking/bridge
> +A bridge is a way to connect multiple Ethernet segments together in a protocol
> +independent way. Packets are forwarded based on Layer 2 destination Ethernet
> +address, rather than IP address (like a router). Since forwarding is done
> +at Layer 2, all Layer 3 protocols can pass through a bridge transparently.
>  
> -The bridge-utilities are maintained at:
> -   git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/bridge-utils.git
> +Bridge kAPI
> +===========
>  
> -Additionally, the iproute2 utilities can be used to configure
> -bridge devices.
> +Here are some core structures of bridge code.
>  
> -If you still have questions, don't hesitate to post to the mailing list 
> -(more info https://lists.linux-foundation.org/mailman/listinfo/bridge).
> +.. kernel-doc:: net/bridge/br_private.h

nit: Building htmldocs reports:

 ./net/bridge/br_private.h:240: warning: Function parameter or member 'tnode' not described in 'net_bridge_vlan'
 ./net/bridge/br_private.h:240: warning: Function parameter or member 'tinfo' not described in 'net_bridge_vlan'

...