Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp34971yba; Thu, 2 May 2019 19:06:47 -0700 (PDT) X-Google-Smtp-Source: APXvYqytB/qRh5V5M3DDERKhCfxZ7nGpk1eS9Zd6Ie1ZWElGJkTPNy26CqfV4cMyM+5fWkNASY1s X-Received: by 2002:a63:4c24:: with SMTP id z36mr5379379pga.130.1556849207771; Thu, 02 May 2019 19:06:47 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556849207; cv=none; d=google.com; s=arc-20160816; b=DJo38ybnNa4yArKS06C0WczExDMNK48Eix9LWl5FblEeH1vGsl+SIowe7S43euKg+/ wRYWQ5GHY2zMXhXYjw++3NjBV9HIsYeCvssfDdtoPcsQjgNDd0jz3OjPo23bPtJOmVRw uZCq8jdnAL0I+zjlgLjIcGhZMHDWLTx4Hj40gJ4AsO5OSxveQIqsnihpEmYwAirMLVvY +Jkkff0xIBo4mkZ7e9vEtsI5OAIb7GLORIiTmbzrZcC0iue0hkXKEGHtR+8lBzf5ySyo nn2LzaKz3Dttu+470tGXwsTgmHI/hqLBaFZwh8rBgD8ddrcMtXWLP+q1KIjSh/oI94DU VPzQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding :content-language:in-reply-to:mime-version:user-agent:date :message-id:from:references:cc:to:subject:dkim-signature; bh=YJQaUOy07zWYs8zVSTxJU7bh0o5le6pfH8RqO6AY0VI=; b=wt4NbiRi2cOr/1z18tHLn72pzclroe6RDPClFtmEVSgK6NPUrQpdL712YBMRAzXoWe u46po/c//8j+P2O8zTFKLrbveBHR/NRTrn+alZh5i6qDCGzr39c1xfFgaL+IgG5uQ634 2KEmGe/Fvb3mpwDsICqPR3ke9LGhsxtvUWcfI1u1ds7btyAYhp8PauaKieRhyQkhzMhQ PMLMWm8HX/FLBAvcAKqoW1baFrBooGJDdJOwAzog2QDObk5C+ml73doF1go4NQOUSWAn UKOFqmbJK7E/x+BlvtXH+lPU/bNGyzDPQ9y8X/kmYPZDJPBTOeCfLZ7y1WoW5pnHiWKg lTIA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=merlin.20170209 header.b=Z5B4A8IJ; 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 j19si684325pfe.124.2019.05.02.19.06.31; Thu, 02 May 2019 19:06:47 -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=fail header.i=@infradead.org header.s=merlin.20170209 header.b=Z5B4A8IJ; 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 S1726608AbfECBqW (ORCPT + 99 others); Thu, 2 May 2019 21:46:22 -0400 Received: from merlin.infradead.org ([205.233.59.134]:60340 "EHLO merlin.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726220AbfECBqW (ORCPT ); Thu, 2 May 2019 21:46:22 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=merlin.20170209; h=Content-Transfer-Encoding:Content-Type: In-Reply-To:MIME-Version:Date:Message-ID:From:References:Cc:To:Subject:Sender :Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=YJQaUOy07zWYs8zVSTxJU7bh0o5le6pfH8RqO6AY0VI=; b=Z5B4A8IJMzU3eUUJU6fm12bf+j 0iIQZOhqBc8aToHebYQcsHdIs/42x3dJGQNmFB6QNBUb5RmJRBoU14y0E/DvXyrdnlsO+5nf5sj6i NsYhxLQGrTq1XgVBAN8run654mgz8duAunnY5EvDuCqJHaNl8Me27BTFd8+zikrPPmcVjjAM/0zjw H1Xd85N/Q9W/1OmNEFUoWi9gbwz5lCfoAi4u1QyPmi14boPR7HbNEc1Cr8L86lphEYU9oYDno3s/p 3uhrhvGCzl07dMS4ZG89yAe48+aobUZq/qfFSGznEpXIXfdfrMcDlPuYSQDKIyCm4KEKeV9WVs4yP 4iEEPozw==; Received: from static-50-53-52-16.bvtn.or.frontiernet.net ([50.53.52.16] helo=midway.dunlab) by merlin.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hMNHG-0006oZ-Ew; Fri, 03 May 2019 01:46:18 +0000 Subject: Re: [RFC PATCH 3/5] kobject: Fix kernel-doc comment first line To: "Tobin C. Harding" , 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 References: <20190502023142.20139-1-tobin@kernel.org> <20190502023142.20139-4-tobin@kernel.org> <20190502073823.GQ26546@localhost> <20190502082539.GB18363@eros.localdomain> <20190502083922.GR26546@localhost> <20190503014015.GC7416@eros.localdomain> From: Randy Dunlap Message-ID: <8e237ab7-681b-dccf-792f-264e3f6fcd2d@infradead.org> Date: Thu, 2 May 2019 18:46:16 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.6.1 MIME-Version: 1.0 In-Reply-To: <20190503014015.GC7416@eros.localdomain> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 5/2/19 6:40 PM, Tobin C. Harding wrote: > 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 :) I have seen this discussion before also. And sometimes it is not even a discussion -- it's more of an edict. To which I object/disagree. The current (or past) comment style is perfectly fine IMO. No caps needed. No ending '.' needed. -- ~Randy