From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1423107AbcBQTpH (ORCPT ); Wed, 17 Feb 2016 14:45:07 -0500 Received: from mail-yw0-f176.google.com ([209.85.161.176]:36394 "EHLO mail-yw0-f176.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S965253AbcBQTpE (ORCPT ); Wed, 17 Feb 2016 14:45:04 -0500 Date: Wed, 17 Feb 2016 14:45:01 -0500 From: Tejun Heo To: Jonathan Corbet 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: <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> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20160217111338.205bcaeb@lwn.net> User-Agent: Mutt/1.5.24 (2015-08-30) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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