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 X-Spam-Level: X-Spam-Status: No, score=-0.6 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS autolearn=no autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2A257C433E0 for ; Thu, 21 May 2020 11:45:10 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id CF2832070A for ; Thu, 21 May 2020 11:45:09 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (2048-bit key) header.d=infradead.org header.i=@infradead.org header.b="W9ZmJYD7" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org CF2832070A Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=infradead.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 6202680008; Thu, 21 May 2020 07:45:09 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 5D13780007; Thu, 21 May 2020 07:45:09 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 4E6D180008; Thu, 21 May 2020 07:45:09 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id 3258280007 for ; Thu, 21 May 2020 07:45:09 -0400 (EDT) Received: from smtpin19.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay02.hostedemail.com (Postfix) with ESMTP id E31CB4403 for ; Thu, 21 May 2020 11:45:08 +0000 (UTC) X-FDA: 76840545096.19.leg80_4a01cd1cd5037 X-HE-Tag: leg80_4a01cd1cd5037 X-Filterd-Recvd-Size: 3102 Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.133]) by imf45.hostedemail.com (Postfix) with ESMTP for ; Thu, 21 May 2020 11:45:08 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=In-Reply-To:Content-Type:MIME-Version :References:Message-ID:Subject:To:From:Date:Sender:Reply-To:Cc: Content-Transfer-Encoding:Content-ID:Content-Description; bh=n3wNjOWW/M+k090LRDIAmyiMPbKdHf37oT1rYkljmBM=; b=W9ZmJYD7He5feXfFpYg7aZiNz1 AkJQD/eqzjC3vwUTIHrto8lBBdvemNDDnitOGTubnE+DRoQtzQ1nsDvuhHjiaMzS6O2Ag2PnlQiBB DMrdvuYkwdaPlatkKRVme9GU/2Psq1cqicSnyNQ/J/5S1hhAsZ8B6ZHC5L2OOyWk1Q73POjsY5DlJ Fb4Nv2wXdf/RL4mo6bwVQj167dV8sXuNaqU9HL/NQ36iN4Wkj8qcHqjZ3xZoi7OJVjjbhw4kL21ag 8AvqdIL28/PZwoGMLQDTj1sgoEVtwWco9zMzI3t+u8HKuM5hR9QVkac9CKolASCORE27m7Wu/OiOI ZzLVEpjg==; Received: from willy by bombadil.infradead.org with local (Exim 4.92.3 #3 (Red Hat Linux)) id 1jbjdK-00010a-Rh; Thu, 21 May 2020 11:45:06 +0000 Date: Thu, 21 May 2020 04:45:06 -0700 From: Matthew Wilcox To: linux-mm@kvack.org, Dave Hansen , Andrew Morton Subject: Re: [PATCH] mm: add comments on pglist_data zones Message-ID: <20200521114506.GB28818@bombadil.infradead.org> References: <20200520205443.2757414-1-ben.widawsky@intel.com> <20200520232235.GD16070@bombadil.infradead.org> <20200521045300.vh2ukn63rr423q4n@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20200521045300.vh2ukn63rr423q4n@intel.com> 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 Wed, May 20, 2020 at 09:53:00PM -0700, Ben Widawsky wrote: > On 20-05-20 16:22:35, Matthew Wilcox wrote: > > On Wed, May 20, 2020 at 01:54:43PM -0700, Ben Widawsky wrote: > > > While making other modifications it was easy to confuse the two struct > > > members node_zones and node_zonelists. For those already familiar with > > > the code, this might seem to be a silly patch, but it's quite helpful to > > > disambiguate the similar-sounding fields > > > > > > While here, add a small comment on why nr_zones isn't simply MAX_NR_ZONES > > > > It seems like a real shame to write all this excellent documentation > > and not format it as kernel-doc. > > I admit, I didn't look at all the kernel-doc files. Is there precedent there for > documenting struct members like this? I'd be more than happy to try to document > everything I've dug up in coming up to speed here. > > I've used the docs from Mel quite a bit and would very much like to pay it > forward, as it were. I appreciate your willingness! Fortunately, we have excellent documentation on adding more documentation ;-) Documentation/doc-guide/kernel-doc.rst is where you'll want to start. 'Structure, union, and enumeration documentation' is the section. Do read through the whole section before jumping in because you might find it more clear to use the style in 'In-line member documentation comments' rather than the style documented first.