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=-2.4 required=3.0 tests=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI, SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 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 C2C0CC35641 for ; Sat, 22 Feb 2020 02:15:53 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 71B59206E2 for ; Sat, 22 Feb 2020 02:15:53 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=nvidia.com header.i=@nvidia.com header.b="GpbSiANP" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 71B59206E2 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=nvidia.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 022C06B0003; Fri, 21 Feb 2020 21:15:53 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id F14986B0006; Fri, 21 Feb 2020 21:15:52 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id E04446B0007; Fri, 21 Feb 2020 21:15:52 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0223.hostedemail.com [216.40.44.223]) by kanga.kvack.org (Postfix) with ESMTP id C677A6B0003 for ; Fri, 21 Feb 2020 21:15:52 -0500 (EST) Received: from smtpin07.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay02.hostedemail.com (Postfix) with ESMTP id 73FB452D0 for ; Sat, 22 Feb 2020 02:15:52 +0000 (UTC) X-FDA: 76516147344.07.time31_6d6d6f9722346 X-HE-Tag: time31_6d6d6f9722346 X-Filterd-Recvd-Size: 4839 Received: from hqnvemgate25.nvidia.com (hqnvemgate25.nvidia.com [216.228.121.64]) by imf40.hostedemail.com (Postfix) with ESMTP for ; Sat, 22 Feb 2020 02:15:51 +0000 (UTC) Received: from hqpgpgate101.nvidia.com (Not Verified[216.228.121.13]) by hqnvemgate25.nvidia.com (using TLS: TLSv1.2, DES-CBC3-SHA) id ; Fri, 21 Feb 2020 18:15:16 -0800 Received: from hqmail.nvidia.com ([172.20.161.6]) by hqpgpgate101.nvidia.com (PGP Universal service); Fri, 21 Feb 2020 18:15:50 -0800 X-PGP-Universal: processed; by hqpgpgate101.nvidia.com on Fri, 21 Feb 2020 18:15:50 -0800 Received: from [10.110.48.28] (10.124.1.5) by HQMAIL107.nvidia.com (172.20.187.13) with Microsoft SMTP Server (TLS) id 15.0.1473.3; Sat, 22 Feb 2020 02:15:50 +0000 Subject: Re: [LSF/MM/BPF TOPIC]: MM documentation To: Mike Rapoport , CC: References: <20200206165305.GB17499@linux.ibm.com> X-Nvconfidentiality: public From: John Hubbard Message-ID: <9556c040-7e5e-f23f-0137-b167e90ef1ef@nvidia.com> Date: Fri, 21 Feb 2020 18:15:49 -0800 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.5.0 MIME-Version: 1.0 In-Reply-To: <20200206165305.GB17499@linux.ibm.com> X-Originating-IP: [10.124.1.5] X-ClientProxiedBy: HQMAIL111.nvidia.com (172.20.187.18) To HQMAIL107.nvidia.com (172.20.187.13) Content-Type: text/plain; charset="utf-8" Content-Language: en-US Content-Transfer-Encoding: 7bit DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=nvidia.com; s=n1; t=1582337716; bh=IU50OnT3zlyYOwzkKJhXOZNskJfkQ4p7O3A1hFqyDyk=; h=X-PGP-Universal:Subject:To:CC:References:X-Nvconfidentiality:From: Message-ID:Date:User-Agent:MIME-Version:In-Reply-To: X-Originating-IP:X-ClientProxiedBy:Content-Type:Content-Language: Content-Transfer-Encoding; b=GpbSiANPibBPoxaZ/HoUT6fFDhH11RZV9Ho62AXfy2xfk7NJ17/0tuBVpguZ0qqzs mPS52fiVSbRlrvO3a3MX23B+hmCyI6mAf3H98q49vnk0zqHfv9LAQ0otE/0ph7rNC2 Q9wAnOU195ZtyF/IiZlI0oO9Rry7gQYL7d7xCniCLfUy89GbMOhimNIh8PYYV1mLTL O6iJ5iB6FmW2fZgflhlG3DNpHQ7Ju7/76/NuRa+AEjbuSWLapvIehEroHOTxgdeJjq xBnfoH3TFp54bs4v0goPXPJ06+GawCgHrB1U7kiW0zp6MwrYfjSPj9xoSkUT9NAI6j pq2MvHk2/N8Ow== 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 2/6/20 8:53 AM, Mike Rapoport wrote: > The mm documentation is, well, not entirely up to date. We can opt for > dropping the outdated parts, which would generate a nice negative > diffstat, but identifying the outdated documentation requires nearly > as much effort as updating it, so I think that making and keeping > the docs up to date would be a better option. > > I'd like to discuss what can be done process-wise to improve the > situation. > > Some points I had in mind: > > * Pay more attention to docs during review > * Set an expectation level for docs accompanying a changeset > * Spend some cycles to review and update the existing docs > * Spend some more cycles to add new documentation > > I'd appreciate a discussion about how we can get to the second edition > of "Understanding the Linux Virtual Memory Manager", what are the gaps > (although they are too many), and what would be the best way to close > these gaps. > It's a good topic to have. You know, I've noticed something interesting about the documentation: the *.rst documents tend to provide critical insight (even if they're imperfect for various reaons), and furthermore, the generated HTML from the .rst docs is very nicely readable (visually) as well. The kerneldoc documentation is different: it's also got absolutely critical content, and the native source (in .c/.h files) is also very readable. However, the generated HTML is *significantly* less readable than any of the other 3 items I've listed here. That's mainly because the system picks up all kerneldoc items, even the short and less informative ones. Yes, we can keep trying to make the kerneldoc documentation cleaner. But it's also reasonable to claim that their are "tiers" of quality, and it's OK for kerneldoc comments to be at a lower tier than the nice .rst docs. In fact, we sort of implicitly do so. When browsing at the HTML level, I wish there were maybe some slight visual indicator of these tiers. Because honestly, it seems reasonable for kernel developers to do something like this: * If reading at the HTML level, read the "docs" (.rst --> .html docs). * Once the docs move to the kerneldoc level, you really want the source code right next to the (often cryptic) kerneldoc documentation. So at that point, I want out of the HTML, but the HTMl docs are all intermingled. Maybe it's wrong to want this, but I'm gonna say it anyway. :) thanks, -- John Hubbard NVIDIA