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

[Tejun Heo]

Hello, Jonathan.

On Wed, Feb 17, 2016 at 11:13:38AM -0700, Jonathan Corbet wrote:
> This might come as a real surprise to the subsystems that are putting a
> lot of work into said docs.  *You* might not find them useful but, for
> example, the DRM folks have told me that they credit better docs with an
> increase in the quality of the code submissions they are getting.  Much
> of that work is inline, but in the code is not always the best place for
> everything.
>
> There's a set of us working to improve the generation system, making it
> so that even ordinary kernel developers can manage to get it to work.
> Sorry if you don't this stuff useful, but I hope you'll not mind if
> others keep the documentation in good form?

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.  It ends up locking up general
information in a format which is awkward to access and update.  While
keeping things mechanically synced wasn't that problematic, I'm not
sure it has been a productive direction in terms of documentation.

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?

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?

Thanks.

-- 
tejun