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: 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
