Re: [PATCH RFC 09/22] block, cfq: replace CFQ with the BFQ-v0 I/O scheduler

[Tejun Heo]

Hello,

On Wed, Feb 17, 2016 at 12:56:01PM -0700, Jonathan Corbet wrote:
> It's probably useful for those who want to understand and hack on it.  But
> yes, the audience will surely be smaller.

Wouldn't more accessible in-line comments be better for that audience?
They're looking at the code in question anyway.

> > I'm not trying to sabotage documentation effort but for large internal
> > struct I find it a lot easier to understand and update to have grouped
> > fields with sectional comments and the benefits of using docbook style
> > comments don't seem clear to me.  Is it beneficial to use formatted
> > comments for all internal structs even when they aren't interface to
> > anything and there's no matching template file?
> 
> The kerneldoc comments can be interspersed within the structure, allowing
> for grouping; that's a relatively recent addition.

Ah, glad to hear it.  That's a lot better.

> And yes, for internal structs, unless you're making a larger document
> covering theory of operation etc. there may not be a whole lot of value in
> the formatted comments.  But they shouldn't hurt either :)

Actually, I think it hurts a bit.  I've never felt it with function
comments probably because the number of params is limited but with
long structs kerneldoc tends to get in the way.  I suspect that the
format at least sometimes ends up making people produce worse
documentation by forcing a structure which doesn't quite fit the
purpose.  People feel obligated to make item-by-item documentation
when grouped explanation works better and then end up making
unnecessary compromises on the content.  Before, when the comment must
be before the definition, it could get pretty bad as all the itemized
information should be up there and it's unclear where to put
information for groups and it isn't difficult to imagine people going
"forget it".

If we're gonna generally encourage kerneldoc documentation of structs,
I think we need better tools and guidelines so that it doesn't end up
worsening the quality and accesbility of documentation.

Thanks.

-- 
tejun