On Fri, Mar 27, 2020 at 11:11:06AM -0600, Jonathan Corbet wrote: > On Fri, 27 Mar 2020 09:50:22 -0700 > Matthew Wilcox <willy@xxxxxxxxxxxxx> wrote: > > > Let me just check I understand Jani's proposal here. You want to change > > > > * Return: Number of pages, or negative errno on failure > > > > to > > > > * Return > > * ~~~~~~ > > * Number of pages, or negative errno on failure > > > > If so, I oppose such an increase in verbosity and I think most others > > would too. If not, please let me know what you're actually proposing ;-) > > I told you there would be resistance :) Happy to help out! > I think a reasonable case can be made for using the same documentation > format throughout our docs, rather than inventing something special for > kerneldoc comments. So I personally don't think the above is terrible, > but as I already noted, I anticipate resistance. > > An alternative would be to make a little sphinx extension; then it would > read more like: > > .. returns:: Number of pages, except when the moon is full > > ...which would still probably not be entirely popular. I certainly see the value in consistency throughout our documentation. But I don't think it's a given that the documentation of the return value is necessarily its own section. I see kernel-doc as being more about semantic markup and the rst files as being a presentation markup. So I'm fine with Return:: introducing a list or Example:: introducing a code section; these are special purpose keywords. I'm not a fan of using raw rst in kernel-doc. Of course if we can make the kernel-doc and rst languages the same for the same concepts, that's great.
