Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp6931168yba; Thu, 2 May 2019 00:40:45 -0700 (PDT) X-Google-Smtp-Source: APXvYqyHNfaKf67lg8fcM9zbJVB03uKMoJYOjuCXYGy4Ho6PMx6RoIhn0utJ9pMLKwzYfDWnCEbS X-Received: by 2002:a63:d016:: with SMTP id z22mr2558139pgf.116.1556782845476; Thu, 02 May 2019 00:40:45 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1556782845; cv=none; d=google.com; s=arc-20160816; b=C1K4LWBNhBRk0guXPk0Knq76ZO6b4kP+abziE59p22UhZzfz7BvPJ5wxpINddVrPgI In13wjFhqV0SuW2mrjCY4RokMcef+vRX8AJKQ5bV72Jo53ifnNkdX4Df7IXkMFWXGwoi JMAUdPc9Nyg4z5Xyra4ckokNUwB+FLG726hxDg2HnkGOQ+7DFuLNdFmaOF9SvDRVMZMp JpTtp3/Lppic37W7lHtB+sqCC2+PQDoG8FH65VssDfkdyKVFJ0cutGzoq/UNR4Gpug/P PkZ+/wUMH00zK2glBBBOv/GJ7/J32ZXXoTNQxfGQQTytGNe8QSvwGM7Y4QpiriQdeSiY jCLg== 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; bh=BBJ1hjxqa+5BnXyt7pCtMPz5hZf7jhfxyIk6LZ9P3rM=; b=Nt1l0Iwll04La50KP2RMWpelduiHgFMOTpoYKSoIUSOGSc51vua2gA4zH3aId9URVl WRO7QzlEs3rZQxEgIMIvj8nAGPr0cu8LzK8nwpEeabkSKHoh9L2aOPH+AlGABm1wih4q oeD6raXNZoP89Z8iuCeb9hcv3hocNZ+lDLKqZFlDQr1FksgXHYiImWoXczMZEMZ2PyvN RkiriE+HoaoD5n8oExRoFSd5pReBy12DwnNWEAFmZwaI5XHM1KrT8CsMGRw50t2ts+as IDDrDs0ro2BF2jcFgBLQb3xb19q9+RTkO0utHY2AanT7sthCNyDthpcCCz829To1DHLs nFMA== ARC-Authentication-Results: i=1; mx.google.com; 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; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id w7si42945374plp.341.2019.05.02.00.40.30; Thu, 02 May 2019 00:40:45 -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; 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; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726343AbfEBHiR (ORCPT + 99 others); Thu, 2 May 2019 03:38:17 -0400 Received: from mail-lj1-f195.google.com ([209.85.208.195]:38032 "EHLO mail-lj1-f195.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725795AbfEBHiQ (ORCPT ); Thu, 2 May 2019 03:38:16 -0400 Received: by mail-lj1-f195.google.com with SMTP id e18so1265428lja.5; Thu, 02 May 2019 00:38:15 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=BBJ1hjxqa+5BnXyt7pCtMPz5hZf7jhfxyIk6LZ9P3rM=; b=fZLai2Hgs7iH0UDuaGecGdq++MJ55RYWa2BuhClRowkPQw+hXnURfJH9Pplu3ziXxc p0mhyARMSDDjHFcbfGEEXcFQsLbqpogawacIXVDQbhJMhrYkfQBmp9/jmu0WpgMT/zyo BjuDkIK4On9GSuaz5Vn5xXGcyVfnR52GIzjmmt8tGXixF9FZErMSCZkM/WqLleIMYohz LDou1w29UXbxF+eSJQnMcQ6tetr94fLYzvRrNkLnV/hOpdsTaZYf25JLOoqN6VI/eZFL DGmDfCA5qeS6mpda7fDomJrI61aj95W46vsd5rOpdaP/NusKjMOZWPeKjkoeXZAPwd85 MbuA== X-Gm-Message-State: APjAAAWIHOq9TfCLzYo6hrjSnVjLR+md+IyTU+6XcQJdiThJpa0yGSBx KudNG5gOYnUSrVc7bBNKrQ0= X-Received: by 2002:a2e:880b:: with SMTP id x11mr640795ljh.4.1556782694716; Thu, 02 May 2019 00:38:14 -0700 (PDT) Received: from xi.terra (c-74bee655.07-184-6d6c6d4.bbcust.telenor.se. [85.230.190.116]) by smtp.gmail.com with ESMTPSA id y20sm9328553lfe.8.2019.05.02.00.38.13 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 02 May 2019 00:38:13 -0700 (PDT) Received: from johan by xi.terra with local (Exim 4.91) (envelope-from ) id 1hM6IR-0006zW-Bf; Thu, 02 May 2019 09:38:23 +0200 Date: Thu, 2 May 2019 09:38:23 +0200 From: Johan Hovold To: "Tobin C. Harding" Cc: Josh Poimboeuf , Jiri Kosina , Miroslav Benes , Petr Mladek , Greg Kroah-Hartman , "Rafael J. Wysocki" , Joe Lawrence , 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: <20190502073823.GQ26546@localhost> References: <20190502023142.20139-1-tobin@kernel.org> <20190502023142.20139-4-tobin@kernel.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190502023142.20139-4-tobin@kernel.org> 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 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 Johan