From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id 342A3C433F5 for ; Mon, 28 Feb 2022 05:19:38 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 66D0F8D0002; Mon, 28 Feb 2022 00:19:38 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 61CB68D0001; Mon, 28 Feb 2022 00:19:38 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 4E4088D0002; Mon, 28 Feb 2022 00:19:38 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0127.hostedemail.com [216.40.44.127]) by kanga.kvack.org (Postfix) with ESMTP id 3B64E8D0001 for ; Mon, 28 Feb 2022 00:19:38 -0500 (EST) Received: from smtpin17.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay04.hostedemail.com (Postfix) with ESMTP id DF8099BBA1 for ; Mon, 28 Feb 2022 05:19:37 +0000 (UTC) X-FDA: 79191035994.17.7F2F95D Received: from smtp-out1.suse.de (smtp-out1.suse.de [195.135.220.28]) by imf30.hostedemail.com (Postfix) with ESMTP id 6D8AF80003 for ; Mon, 28 Feb 2022 05:19:37 +0000 (UTC) Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by smtp-out1.suse.de (Postfix) with ESMTPS id E6BD921155; Mon, 28 Feb 2022 05:19:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1646025575; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=OsOdRKyOPTsqFVySVeje99MCazN8FHXIRZGctTB3Fjc=; b=1aDnYNyCMKoqi7852ELng+RjN9qj4H3oZKIs6lZKTxoiwJvkWraBZGmj+Lgr7uB+1SHFJz Yh2mZu17ZFxMhdj6twoLK7xeDGS6uw7JuUWs/fN+ewmZBdcdER+polBa/xGaRr74gldhFA Ag1t4rw/IZDJ70lWUTD3DCkE1pDKQVg= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1646025575; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=OsOdRKyOPTsqFVySVeje99MCazN8FHXIRZGctTB3Fjc=; b=ETy1bbk4AvRTgoyR516RJsfNTn47d24xVl6EFjxT7PerkTAmm+E/x1KFcnx2xiTY9paC/z 4vNKWy2UyfSPGfDg== Received: from imap2.suse-dmz.suse.de (imap2.suse-dmz.suse.de [192.168.254.74]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-521) server-digest SHA512) (No client certificate requested) by imap2.suse-dmz.suse.de (Postfix) with ESMTPS id 6E5C712FC5; Mon, 28 Feb 2022 05:19:28 +0000 (UTC) Received: from dovecot-director2.suse.de ([192.168.254.65]) by imap2.suse-dmz.suse.de with ESMTPSA id 5BzICmBbHGIXfAAAMHmgww (envelope-from ); Mon, 28 Feb 2022 05:19:28 +0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit MIME-Version: 1.0 From: "NeilBrown" To: "Andrew Morton" Cc: "Jan Kara" , "Wu Fengguang" , "Jaegeuk Kim" , "Chao Yu" , "Jeff Layton" , "Ilya Dryomov" , "Miklos Szeredi" , "Trond Myklebust" , "Anna Schumaker" , "Ryusuke Konishi" , "Darrick J. Wong" , "Philipp Reisner" , "Lars Ellenberg" , "Paolo Valente" , "Jens Axboe" , linux-doc@vger.kernel.org, linux-mm@kvack.org, linux-nilfs@vger.kernel.org, linux-nfs@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-f2fs-devel@lists.sourceforge.net, linux-ext4@vger.kernel.org, ceph-devel@vger.kernel.org, drbd-dev@lists.linbit.com, linux-kernel@vger.kernel.org, linux-block@vger.kernel.org Subject: Re: [PATCH 02/11] MM: document and polish read-ahead code. In-reply-to: <20220227204728.b2eb5dd94ecc3e86912bacad@linux-foundation.org> References: <164447124918.23354.17858831070003318849.stgit@noble.brown>, <164447147257.23354.2801426518649016278.stgit@noble.brown>, <20220210122440.vqth5mwsqtv6vjpq@quack3.lan>, <164453611721.27779.1299851963795418722@noble.neil.brown.name>, <20220224182622.n7abfey3asszyq3x@quack3.lan>, <164602251992.20161.9146570952337454229@noble.neil.brown.name>, <20220227204728.b2eb5dd94ecc3e86912bacad@linux-foundation.org> Date: Mon, 28 Feb 2022 16:19:24 +1100 Message-id: <164602556430.20161.5451268677064506613@noble.neil.brown.name> X-Rspamd-Queue-Id: 6D8AF80003 X-Stat-Signature: uheamoxxa13j3cmd9fdc5hfpfa3m7f7z X-Rspam-User: Authentication-Results: imf30.hostedemail.com; dkim=pass header.d=suse.de header.s=susede2_rsa header.b=1aDnYNyC; dkim=pass header.d=suse.de header.s=susede2_ed25519 header.b=ETy1bbk4; dmarc=pass (policy=none) header.from=suse.de; spf=pass (imf30.hostedemail.com: domain of neilb@suse.de designates 195.135.220.28 as permitted sender) smtp.mailfrom=neilb@suse.de X-Rspamd-Server: rspam03 X-HE-Tag: 1646025577-592170 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: On Mon, 28 Feb 2022, Andrew Morton wrote: > On Mon, 28 Feb 2022 15:28:39 +1100 "NeilBrown" wrote: > > > When writing documentation the intent of the author is of some interest, > > but the behaviour of the code is paramount. > > uh, er, ah, no. The code describes the behaviour of the code. The > comments are there to describe things other than the code's behaviour. > Things such as the author's intent. > > Any deviation between the author's intent and the code's behaviour is > called a "bug", so it's pretty important to understand authorial > intent, no? When the author is writing the documentation - then yes - definitely. When the "author" is several different people over a period of years, then it is not even certain that there is a single unified "intent". The author's intent is less interesting not so much because it is less relevant, but because it is less available. So when writing third-party post-hoc documentation, the focus has to be on the code, though with reference to the intent to whatever extent it is available. Bugs then show up where the actual behaviour turns out to be impossible to document coherently. Thanks, NeilBrown