netdev - Re: [RFC Draft PATCHv2 net-next] Doc: update bridge doc

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <ZUzY4NXXasJAdEFF@Laptop-X1>
Date: Thu, 9 Nov 2023 21:04:32 +0800
From: Hangbin Liu <liuhangbin@...il.com>
To: Nikolay Aleksandrov <razor@...ckwall.org>
Cc: netdev@...r.kernel.org, "David S . Miller" <davem@...emloft.net>,
	David Ahern <dsahern@...nel.org>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
	Ido Schimmel <idosch@...sch.org>, Roopa Prabhu <roopa@...dia.com>,
	Stephen Hemminger <stephen@...workplumber.org>
Subject: Re: [RFC Draft PATCHv2 net-next] Doc: update bridge doc

Hi Nikolay,

On Wed, Nov 01, 2023 at 01:29:34PM +0200, Nikolay Aleksandrov wrote:
> > diff --git a/include/uapi/linux/if_link.h b/include/uapi/linux/if_link.h
> > index fac351a93aed..6adc0c70e345 100644
> > --- a/include/uapi/linux/if_link.h
> > +++ b/include/uapi/linux/if_link.h
> > @@ -461,6 +461,238 @@ enum in6_addr_gen_mode {
> >   /* Bridge section */
> > +/**
> > + * DOC: The bridge emum defination
> 
> s/emum/enum/
> 
> Below the time is not in seconds though. It is expected in clock_t (seconds
> multiplied by USER_HZ) and also exported. That should be
> better explained as it has caused confusion a lot.

I have done most of the update. But for this I'm not sure how to update.
Should I explain the clock_t defination before all the enum definations?
And how should I describe the time in the enums?
> > + *
> > + * @IFLA_BR_MCAST_LAST_MEMBER_CNT
> > + *   Set multicast last member count, ie the number of queries the bridge
> > + *   will send before stopping forwarding a multicast group after a "leave"
> > + *   message has been received.
> 
> This needs to be explained better. Remove "ie", "It is the number of queries
> the bridge will send", this part needs to be extended what are these queries
> and are they group-specific or general etc. The interval
> and time values below need better explanations of their units and what
> they represent in general. I won't add a comment below each.
> 
> Also please remove the extra new lines between the comments and the
> definitions.

And this one. Which extra new lines do you mean? Are you meaning no blank line
after each enum? e.g.

@IFLA_BR_...
  some comments
@IFLA_BR_...
  some comments

Thanks
Hangbin