Re: [PATCH net-next 03/10] batman-adv: add missing kernel-doc comments

https://netdev-ai.bots.linux.dev/sashiko/#/patchset/20260805143200.722098-1-sw%40simonwunderlich.de?part=3

--- Patch [3]: [PATCH net-next 03/10] batman-adv: add missing kernel-doc comments ---

> > @@ -469,6 +510,17 @@ static int batadv_v_neigh_cmp(struct batadv_neigh_node *neigh1,
> >  	return ret;
> >  }
> >  
> > +/**
> > + * batadv_v_neigh_is_sob() - check whether two B.A.T.M.A.N. V neighbours have
> > + *  a similar or better throughput
> > + * @neigh1: first neighbour to compare
> > + * @if_outgoing1: outgoing interface to use for @neigh1
> > + * @neigh2: second neighbour to compare
> > + * @if_outgoing2: outgoing interface to use for @neigh2
> > + *
> > + * Return: true if the throughput of @neigh2 is at least 3/4 of the
> > + *  @neigh1 throughput
> > + */
> >  static bool batadv_v_neigh_is_sob(struct batadv_neigh_node *neigh1,
> >  				  struct batadv_hard_iface *if_outgoing1,
> >  				  struct batadv_neigh_node *neigh2,
> 
> Discovered by: opus-5 · Missed by: sashiko-gemini
> Does "at least 3/4" match the comparison in the body?  The test is strict:
> 
> 	threshold = ifinfo1->bat_v.throughput / 4;
> 	threshold = ifinfo1->bat_v.throughput - threshold;
> 
> 	ret = ifinfo2->bat_v.throughput > threshold;
> 
> For a neigh1 throughput of 100 the threshold is 75, so an exact 75 on
> neigh2 returns false rather than true.

Correct, will change it to "more than" in a patchset which deals with the 
bonding in B.A.T.M.A.N. V. Shouldn't be too bad enough to force a resubmission 
of this PR.

> 
> The second half is about the direction of the comparison.  The ops contract
> in net/batman-adv/types.h documents the hook the other way around:
> 
> 	 * @is_similar_or_better: check if neigh1 is equally similar or better
> 	 *  than neigh2 for their respective outgoing interface from the metric
> 	 *  prospective

Already stumbled upon that. I am not really interested in B.A.T.M.A.N. V or 
even bonding in B.A.T.M.A.N. V. But I don't think anyone of the developers 
will react. I have therefore documented the background in 
https://www.open-mesh.org/issues/464 and will send a patchset which uses more 
descriptive names and reorders this calculation.

Regards,
	Sven

-----BEGIN PGP SIGNATURE-----

iHUEABYKAB0WIQS81G/PswftH/OW8cVND3cr0xT1ywUCanTRrgAKCRBND3cr0xT1
yzoKAP4tAo9tZkYQ3fhZbmARuA3Zfr0Jg5KcSIH+u2NIcX2rLgD+K2jRljMl6jMC
bTghFlsQ7/TN/andWyX75pkJNiDVDAA=
=yFcm
-----END PGP SIGNATURE-----