Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp51387yba; Thu, 2 May 2019 19:33:06 -0700 (PDT) X-Google-Smtp-Source: APXvYqyIYfKgNrGv0jtRgXkPR30LKR1JeY7h6aYzxQyPBxShj6DNbdlMR8bg+tvpgP5/yZ3r8Cfo X-Received: by 2002:a63:ff26:: with SMTP id k38mr7428193pgi.123.1556850786553; Thu, 02 May 2019 19:33:06 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556850786; cv=none; d=google.com; s=arc-20160816; b=VRA630KC+HSt3sGqoTjEmsC2lcqvHa+G/tjKodu08/gE013qM8tpYF4fa7Gv8RKOtS vJzu/OybFHOvqizZ7WGeod3L9YULWguFy2VQQu4f/PsZs+FZr6N+iY5InOY37gA96yXU MUNGhizu3brdb25UtNvy0fzblluPyxPlGoGv4CN9RC3i+WaLnpMCtfTtepq12VHSV6xK oaGkyFWwFGPtNEQUFIs8bN8TnhQk4WBQiKf7ijpOPlLSQuhJdLnXSCtYygm2gn7V6LBk WWG7hJv1FOmPx9KooGTtq2Y1J92WYstNOMDswQtqZ5BXER12w7L0zJG3hea+XHIgoNTK /A3A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:user-agent:in-reply-to :content-disposition:mime-version:references:message-id:subject:cc :to:from:date:dkim-signature:dkim-signature; bh=lCcAU6v9USd6O6HdXYYD0bpWXJQyvhP17fafAT6vWFg=; b=xEqFuP4eUFO3d4JGeL0TSHh6YyrrW5JXdMA41+ji/6IBY+8huHYMnkX5x9PiezSdM+ kXt531jGIXA1lHcgjMuEoAx7euXpqrilL2FxkEO0NmxQeHwhY7VhgUL5B4vjStzMHLH1 LgznSiEYeQjVmZ8YAaIFbXPJ5SKYdnRGNCiMuSwsP1WH2yyjxByQIWBdk31pBD4GBijU +mqPESXrNqpx/unTgM9QKmdRAfL5u8P/CC8MHk3k03A+L4XyXVo1Ha5svGDlO0X75ALR w14PmF5sU0vPuC6OazAdKdPqmOFNi7NlwA6iE5dMENMraD3X3mazNjwnWx2qFpSLGlMl 4ySw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@tobin.cc header.s=fm3 header.b=llZt1Kn0; dkim=pass header.i=@messagingengine.com header.s=fm2 header.b=plN8q35K; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id m136si786230pga.274.2019.05.02.19.32.51; Thu, 02 May 2019 19:33:06 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=pass header.i=@tobin.cc header.s=fm3 header.b=llZt1Kn0; dkim=pass header.i=@messagingengine.com header.s=fm2 header.b=plN8q35K; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726438AbfECBk7 (ORCPT + 99 others); Thu, 2 May 2019 21:40:59 -0400 Received: from new4-smtp.messagingengine.com ([66.111.4.230]:47551 "EHLO new4-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726128AbfECBk6 (ORCPT ); Thu, 2 May 2019 21:40:58 -0400 Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailnew.nyi.internal (Postfix) with ESMTP id 3DF8314AEE; Thu, 2 May 2019 21:40:57 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute5.internal (MEProxy); Thu, 02 May 2019 21:40:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tobin.cc; h=date :from:to:cc:subject:message-id:references:mime-version :content-type:in-reply-to; s=fm3; bh=lCcAU6v9USd6O6HdXYYD0bpWXJQ yvhP17fafAT6vWFg=; b=llZt1Kn0pG8HKFKAI6d1NqzJGq24SlGJ65lr50ds3GR WgNq3mzcnBhb+1U01cuVhrsB36RtrCjYzYzlX7mYl+yAFp3TMgp7E55ZgA0Gici2 lmYauM1iOH7b7fsT9Rugz8kpo8PF7eLiX0lY4T+m9v0S/Eg9zrHFd2DZU07DdFiB +l+XCUC0R0YEtt1ErbcQgzvi297Erj6LTwiIn25E1GHHl/9w9DuGNFvMg3H8073t bTGNeff/lFluc6nW2E8EC9P8o81Dg2cc8X+H0i0wfhGntVbYGXLi7hXsnyojqeLR +07YxTj+79lNHTn3TEB/cJGazPNp8TozPUs8rc94riQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm2; bh=lCcAU6 v9USd6O6HdXYYD0bpWXJQyvhP17fafAT6vWFg=; b=plN8q35Kpda21thj9QoPxQ IoA5NRiWaJ434/oOSFeEnCNie7ogazP8vDDGCpOJe0PMoVvn9D50dal7553V25+N L3O8CO///B3dN1eb3LN/lKNHaicCuF06fnC29yZFJS7KUUyVT2hIkfT0NcEtzBqP mdMW9j9tCLePN0+YLQjabo6/kMQY59o3DWP6lBArQIfyjIg25kSQasqMaJiy+QKW sggG0c+o4mYihzHsYaaKfxmZmxP9HJboyYyjZuSApCItErJRUw0ZKfE/Y1G0S/X+ AnFQ//tJmwMt6oBkj0hNIW1BTrXt+jRjBbJ9GyXwU4WN8c66C1nQnnS0XVhi4p8g == X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduuddrjedtgdehtdcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenfg hrlhcuvffnffculdduhedmnecujfgurhepfffhvffukfhfgggtuggjofgfsehttdertdfo redvnecuhfhrohhmpedfvfhosghinhcuvedrucfjrghrughinhhgfdcuoehmvgesthhosg hinhdrtggtqeenucffohhmrghinhepkhgvrhhnvghlrdhorhhgnecukfhppeduvddurdeg gedrvddtgedrvdefheenucfrrghrrghmpehmrghilhhfrhhomhepmhgvsehtohgsihhnrd gttgenucevlhhushhtvghrufhiiigvpedt X-ME-Proxy: Received: from localhost (ppp121-44-204-235.bras1.syd2.internode.on.net [121.44.204.235]) by mail.messagingengine.com (Postfix) with ESMTPA id 34C87E4625; Thu, 2 May 2019 21:40:54 -0400 (EDT) Date: Fri, 3 May 2019 11:40:15 +1000 From: "Tobin C. Harding" To: Johan Hovold Cc: "Tobin C. Harding" , Josh Poimboeuf , Jiri Kosina , Miroslav Benes , Petr Mladek , Greg Kroah-Hartman , "Rafael J. Wysocki" , Joe Lawrence , Jonathan Corbet , live-patching@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: [RFC PATCH 3/5] kobject: Fix kernel-doc comment first line Message-ID: <20190503014015.GC7416@eros.localdomain> References: <20190502023142.20139-1-tobin@kernel.org> <20190502023142.20139-4-tobin@kernel.org> <20190502073823.GQ26546@localhost> <20190502082539.GB18363@eros.localdomain> <20190502083922.GR26546@localhost> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190502083922.GR26546@localhost> X-Mailer: Mutt 1.11.4 (2019-03-13) User-Agent: Mutt/1.11.4 (2019-03-13) Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Thu, May 02, 2019 at 10:39:22AM +0200, Johan Hovold wrote: > On Thu, May 02, 2019 at 06:25:39PM +1000, Tobin C. Harding wrote: > Adding Jon to CC > > > > On Thu, May 02, 2019 at 09:38:23AM +0200, Johan Hovold wrote: > > > On Thu, May 02, 2019 at 12:31:40PM +1000, Tobin C. Harding wrote: > > > > kernel-doc comments have a prescribed format. This includes parenthesis > > > > on the function name. To be _particularly_ correct we should also > > > > capitalise the brief description and terminate it with a period. > > > > > > Why do think capitalisation and full stop is required for the function > > > description? > > > > > > Sure, the example in the current doc happen to use that, but I'm not > > > sure that's intended as a prescription. > > > > > > The old kernel-doc nano-HOWTO specifically did not use this: > > > > > > https://www.kernel.org/doc/Documentation/kernel-doc-nano-HOWTO.txt > > > > > > > Oh? I was basing this on Documentation/doc-guide/kernel-doc.rst > > > > Function documentation > > ---------------------- > > > > The general format of a function and function-like macro kernel-doc comment is:: > > > > /** > > * function_name() - Brief description of function. > > * @arg1: Describe the first argument. > > * @arg2: Describe the second argument. > > * One can provide multiple line descriptions > > * for arguments. > > > > I figured that was the canonical way to do kernel-doc function > > comments. I have however refrained from capitalising and adding the > > period to argument strings to reduce code churn. I figured if I'm > > touching the line to add parenthesis then I might as well make it > > perfect (if such a thing exists). > > I think you may have read too much into that example. Many of the > current function and parameter descriptions aren't even full sentences, > so sentence case and full stop doesn't really make any sense. > > Looks like we discussed this last fall as well: Ha, this was funny. By 'we' at first I thought you meant 'we the kernel community' but you actually meant we as in 'me and you'. Clearly you failed to convince me last time :) > https://lkml.kernel.org/r/20180912093116.GC1089@localhost I am totally aware this is close to code churn and any discussion is bikeshedding ... for me just because loads of places don't do this it still looks nicer to my eyes /** * sfn() - Super awesome function. than /** */ sfn() - super awesome function I most likely will keep doing these changes if I am touching the kernel-doc comments for other reasons and then drop the changes if the subsystem maintainer thinks its code churn. I defiantly won't do theses changes in GNSS, GREYBUS, or USB SERIAL. Oh, and I'm totally going to CC you know every time I flick one of these patches, prepare to get spammed :) Cheers, Tobin.