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.6 required=3.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_PASS,T_DKIMWL_WL_HIGH,USER_AGENT_MUTT autolearn=ham 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 C0294C43219 for ; Thu, 2 May 2019 08:39:17 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 901642075E for ; Thu, 2 May 2019 08:39:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1556786357; bh=IZCrLI8t1vy1cxPi8ehBOWOO05V6OIU6iF+V96Cqr6c=; h=Date:From:To:Cc:Subject:References:In-Reply-To:List-ID:From; b=hevJ4oFE3WN8VG25JKrdqc/8jGv4+D+uC2tsCwbYS3XJrCvUUq9cL8yfkyChzpIAB MXN9eVSJgapMLiD0Fk2uE/vQy2/aqXfkawV7s7UwfUxMrGN9dH1yXMc3mPhUdbu5wS mB8XdBryJP5SVEukaELvDkJaQEaKVFLFZjSt5cJY= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726423AbfEBIjQ (ORCPT ); Thu, 2 May 2019 04:39:16 -0400 Received: from mail-lf1-f65.google.com ([209.85.167.65]:35894 "EHLO mail-lf1-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1725951AbfEBIjP (ORCPT ); Thu, 2 May 2019 04:39:15 -0400 Received: by mail-lf1-f65.google.com with SMTP id u17so1253089lfi.3; Thu, 02 May 2019 01:39:14 -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=9H3BgZp27P7mZ02Xdw3I95aZVZTQBdCTy/G/xueiXik=; b=nYeGkR4fZmRzZYx/+CjyN8vt8N2zjqdITErs5eJI95lz0UJyZd8P5IPbUnMO3jkkcn 3ErCbhbhBJNZ+7jsoBwcxUDR6Dpo07pRJGvBNPIVuJTRTn5cz0TVwDaM1MUtqWmtqJMd uPu9NGunSQ7Oq5UuMHpVUlQI4HTlFcKjO9bH8bgIbM5MLVvChd2i7+UYKmje0jYJiH40 /4ICpU4YRC1rKItl9Ey6gk3mzdWwIyutF01ZmXtUDr60BiFC7fEtvj8HnerSt0pB9BHx 3qArNrTLswPY0lhW2sYYNAiLK3uzymCzKRL3ORfJVM8FPBIwvdo+FrU3vnWD7U8lLPc3 d+bw== X-Gm-Message-State: APjAAAXNBtwmZWuSDn7mFeFdb+GL2q51LYIe/WjBrEyNBUgmL8A1eL34 u4sBtarW14FrJ0Lf/iYJRt0= X-Google-Smtp-Source: APXvYqxz4WgugS9CiMRU6Ex52NCqBvvCTyAbngYF74d1Avin/SP6/y92WlHAmhpIpRXsM4j/eHHuNg== X-Received: by 2002:a19:a8c8:: with SMTP id r191mr1260548lfe.161.1556786353611; Thu, 02 May 2019 01:39:13 -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 m15sm556223lfl.54.2019.05.02.01.39.12 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 02 May 2019 01:39:12 -0700 (PDT) Received: from johan by xi.terra with local (Exim 4.91) (envelope-from ) id 1hM7FS-0001qQ-Gj; Thu, 02 May 2019 10:39:22 +0200 Date: Thu, 2 May 2019 10:39:22 +0200 From: Johan Hovold To: "Tobin C. Harding" Cc: Johan Hovold , "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: <20190502083922.GR26546@localhost> References: <20190502023142.20139-1-tobin@kernel.org> <20190502023142.20139-4-tobin@kernel.org> <20190502073823.GQ26546@localhost> <20190502082539.GB18363@eros.localdomain> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190502082539.GB18363@eros.localdomain> 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 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: https://lkml.kernel.org/r/20180912093116.GC1089@localhost Johan