From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752907AbeDUAKD (ORCPT ); Fri, 20 Apr 2018 20:10:03 -0400 Received: from merlin.infradead.org ([205.233.59.134]:57956 "EHLO merlin.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752209AbeDUAKB (ORCPT ); Fri, 20 Apr 2018 20:10:01 -0400 Subject: Re: [PATCH 1/3] fs: move documentation for thaw_super() where appropriate To: "Luis R. Rodriguez" , Bart Van Assche Cc: "viro@zeniv.linux.org.uk" , "linux-fsdevel@vger.kernel.org" , "mguzik@redhat.com" , "jack@suse.cz" , "linux-block@vger.kernel.org" , "linux-pm@vger.kernel.org" , "rjw@rjwysocki.net" , "ming.lei@redhat.com" , "linux-kernel@vger.kernel.org" References: <20180420235904.27496-1-mcgrof@kernel.org> <20180420235904.27496-2-mcgrof@kernel.org> <0e6973564f4b2c503f343f63ca1209687f53b312.camel@wdc.com> <20180421000719.GH14440@wotan.suse.de> From: Randy Dunlap Message-ID: Date: Fri, 20 Apr 2018 17:09:48 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.7.0 MIME-Version: 1.0 In-Reply-To: <20180421000719.GH14440@wotan.suse.de> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On 04/20/18 17:07, Luis R. Rodriguez wrote: > On Sat, Apr 21, 2018 at 12:01:31AM +0000, Bart Van Assche wrote: >> On Fri, 2018-04-20 at 16:59 -0700, Luis R. Rodriguez wrote: >>> +/** >>> + * thaw_super -- unlock filesystem >>> + * @sb: the super to thaw >>> + * >>> + * Unlocks the filesystem and marks it writeable again after freeze_super(). >>> + */ >> >> Have you verified the output generated by scripts/kernel-doc? Last >> time I checked the output for headers containing a double dash looked >> weird. > > No, I just moved the block of kdoc crap. Randy would have this memorized I'm > sure though so I should just fix the kdoc if its bad while at it. > > Luis > "--" does sound odd. I've never seen it used on purpose. FWIW, I just go by what is in 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. -- ~Randy