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 -- To unsubscribe from this list: send the line "unsubscribe linux-block" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
