Received-SPF: pass (google.com: domain of linux-wireless-owner@vger.kernel.org designates 23.128.96.35 as permitted sender) client-ip=23.128.96.35;
Message-ID: <3ff89e5a9ee6aeddaa771e1ada0faf13ce549f9f.camel@sipsolutions.net>
Subject: Re: [PATCH 08/18] wifi: mac80211: mesh: fix some kdoc warnings
From:   Johannes Berg <johannes@sipsolutions.net>
To:     Jeff Johnson <quic_jjohnson@quicinc.com>,
        gregory.greenman@intel.com
Cc:     linux-wireless@vger.kernel.org,
        Benjamin Berg <benjamin.berg@intel.com>
Date:   Fri, 29 Sep 2023 08:48:23 +0200
In-Reply-To: <ae8e358d-3d02-4167-9232-5da8a2ec3d1c@quicinc.com>
References: <20230928143539.1037500-1-gregory.greenman@intel.com>
         <20230928172905.33fea2968c62.I41d197b570370ab7cad1405518512fdd36e08717@changeid>
         <ae8e358d-3d02-4167-9232-5da8a2ec3d1c@quicinc.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.48.4 (3.48.4-1.fc38) 
MIME-Version: 1.0
Precedence: bulk

Hi,

> > +++ b/net/mac80211/mesh.c
> > @@ -56,6 +56,8 @@ static void ieee80211_mesh_housekeeping_timer(struct =
timer_list *t)
> >    *
> >    * This function checks if the mesh configuration of a mesh point mat=
ches the
> >    * local mesh configuration, i.e. if both nodes belong to the same me=
sh network.
> > + *
> > + * Returns: %true if both nodes belong to the same mesh
>=20
> I thought kdoc used Return: not Returns:
>=20
> <https://static.lwn.net/kerneldoc/doc-guide/kernel-doc.html#function-docu=
mentation>

Huh, indeed.

I'm sure this actually fixed it though because we did start running
kernel-doc on this code internally (via W=3D1), the issue at hand was that
we used to compile without mesh (not supported by iwlwifi) and now added
it for hwsim testing.

So ... I looked, and indeed _both_ are accepted:

scripts/kernel-doc:

        } elsif ($newsection =3D~ m/^returns?$/i) {
            $newsection =3D $section_return;
        } elsif ($newsection =3D~ m/^\@return$/) {
            # special: @return is a section, not a param description
            $newsection =3D $section_return;


which I guess means

 /**
  * foo - ...
  *
  * Returns: bar
  */

and

 /**
  * foo - ...
  *
  * Return: bar
  */

and

 /**
  * foo - ...
  *
  * @return
  * bar
  */

are all accepted.


Though "Return:" is more common, perhaps due to the docs:

$ git grep ' \* Returns:' -- | wc -l
3066
$ git grep ' \* Return:' -- | wc -l
9189


Personally, I find "Returns: %true if both nodes ..." to be nicer to
read, since it's more like a sentence?

But then again it depends on whether you're reading it as a description
or an instruction, I guess. "Returns: something" is a description, and
"Return: something" is an instruction (for the function). Hmm.

I'm inclined to say I like the descriptive text better, but since it
shows up in the generated documentation with "Return" anyway, maybe it's
better to have it in the same way in the code?

Though of course it's (slightly) easier to just apply it as is :)

What do you (and others!) think? Does it matter?

johannes