Messages in this thread | | | Date | Wed, 17 Feb 2016 12:56:01 -0700 | From | Jonathan Corbet <> | Subject | Re: [PATCH RFC 09/22] block, cfq: replace CFQ with the BFQ-v0 I/O scheduler |
| |
On Wed, 17 Feb 2016 14:45:01 -0500 Tejun Heo <tj@kernel.org> wrote:
> I see. My impression is mostly from libata docbook which was painful > to keep in sync and didn't really seem to be that helpful to many. A > lot of that was from the template being in xml format which is painful > to read in the source format.
Getting rid of XML is a big part of the current effort; I see it as a real impediment to dealing with the docs in every way, from reading the source to writing docs to coping with the toolchain. We won't miss it.
The current leader for a replacement seems to be ReStructuredText (a simple markup language like markdown), but that has not yet been decided.
> Another aspect is that while those types of generated docs can be a > lot more useful for midlayers like drm or even libata with large > interface surface that new low level driver writers may have to learn, > does that hold true for leaf things like bfq? Are generated docs > useful without the matching template file and the accompanying > coordination?
It's probably useful for those who want to understand and hack on it. But yes, the audience will surely be smaller.
> 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.
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 :)
Thanks,
jon
| |