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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20160217125601.0652685f@lwn.net>
Date:	Wed, 17 Feb 2016 12:56:01 -0700
From:	Jonathan Corbet <corbet@....net>
To:	Tejun Heo <tj@...nel.org>
Cc:	Mark Brown <broonie@...nel.org>,
	Paolo Valente <paolo.valente@...aro.org>,
	Jens Axboe <axboe@...nel.dk>,
	Fabio Checconi <fchecconi@...il.com>,
	Arianna Avanzini <avanzini.arianna@...il.com>,
	linux-block@...r.kernel.org, linux-kernel@...r.kernel.org,
	ulf.hansson@...aro.org, linus.walleij@...aro.org
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@...nel.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