From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1161722AbcBQT4G (ORCPT ); Wed, 17 Feb 2016 14:56:06 -0500 Received: from tex.lwn.net ([70.33.254.29]:52927 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1161663AbcBQT4E (ORCPT ); Wed, 17 Feb 2016 14:56:04 -0500 Date: Wed, 17 Feb 2016 12:56:01 -0700 From: Jonathan Corbet To: Tejun Heo Cc: Mark Brown , Paolo Valente , Jens Axboe , Fabio Checconi , Arianna Avanzini , linux-block@vger.kernel.org, linux-kernel@vger.kernel.org, ulf.hansson@linaro.org, linus.walleij@linaro.org Subject: Re: [PATCH RFC 09/22] block, cfq: replace CFQ with the BFQ-v0 I/O scheduler Message-ID: <20160217125601.0652685f@lwn.net> In-Reply-To: <20160217194501.GA4751@mtj.duckdns.org> References: <1454364778-25179-1-git-send-email-paolo.valente@linaro.org> <1454364778-25179-10-git-send-email-paolo.valente@linaro.org> <20160211222210.GC3741@mtj.duckdns.org> <20160212003502.GD1953@sirena.org.uk> <20160217155721.GT3741@mtj.duckdns.org> <20160217160209.GV7544@sirena.org.uk> <20160217170429.GV3741@mtj.duckdns.org> <20160217111338.205bcaeb@lwn.net> <20160217194501.GA4751@mtj.duckdns.org> Organization: LWN.net X-Mailer: Claws Mail 3.12.0 (GTK+ 2.24.28; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 17 Feb 2016 14:45:01 -0500 Tejun Heo 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