On Fri, 2023-09-29 at 08:48 +0200, Johannes Berg wrote: > 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 matches the > > > * local mesh configuration, i.e. if both nodes belong to the same mesh network. > > > + * > > > + * Returns: %true if both nodes belong to the same mesh > > > > I thought kdoc used Return: not Returns: > > > > <https://static.lwn.net/kerneldoc/doc-guide/kernel-doc.html#function-documentation> > > Huh, indeed. > > I'm sure this actually fixed it though because we did start running > kernel-doc on this code internally (via W=1), 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: Hah, I suspect I used "Returns:" here because the file already used it in other places. But, I am also used to "Returns:" from gtk-doc, so it might also have felt natural to me because of that. My hunch is, that it really doesn't matter and it can be left as-is for now. But it is also obviously true that it may be surprising and the extra consistency would help. So, a follow up patch to make everything consistent seems reasonable to me. Benjamin > scripts/kernel-doc: > > } elsif ($newsection =~ m/^returns?$/i) { > $newsection = $section_return; > } elsif ($newsection =~ m/^\@return$/) { > # special: @return is a section, not a param description > $newsection = $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 Intel Deutschland GmbH Registered Address: Am Campeon 10, 85579 Neubiberg, Germany Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de> Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva Chairperson of the Supervisory Board: Nicole Lau Registered Office: Munich Commercial Register: Amtsgericht Muenchen HRB 186928
