Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH] s390/crypto: fix all kernel-doc warnings in vfio_ap_ops.c
To:     Randy Dunlap <rdunlap@infradead.org>, linux-kernel@vger.kernel.org,
        kbuild-all@lists.01.org
Cc:     kernel test robot <lkp@intel.com>,
        Jason Gunthorpe <jgg@nvidia.com>,
        Halil Pasic <pasic@linux.ibm.com>,
        Jason Herne <jjherne@linux.ibm.com>,
        Harald Freudenberger <freude@linux.ibm.com>,
        linux-s390@vger.kernel.org
References: <20210806050149.9614-1-rdunlap@infradead.org>
 <d8f1b065-f7b2-a0f3-f87a-ffdd2f7f2781@linux.ibm.com>
 <1ad57c8d-c0d1-88d9-bcce-3d3501455d8e@infradead.org>
From:   Tony Krowiak <akrowiak@linux.ibm.com>
Message-ID: <fd938029-7d87-4e65-bb2c-b78e9b0175e3@linux.ibm.com>
Date:   Mon, 9 Aug 2021 11:12:53 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.11.0
In-Reply-To: <1ad57c8d-c0d1-88d9-bcce-3d3501455d8e@infradead.org>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0
Precedence: bulk

Thanks Randy.

On 8/6/21 9:38 PM, Randy Dunlap wrote:
> On 8/6/21 6:26 AM, Tony Krowiak wrote:
>> Reviewed-by: Tony Krowiak <akrowiak@linux.ibm.com>
>>
>> Pardon my ignorance, but this is the first I've seen of kernel-doc 
>> warnings.
>> Is there a flag I can set when I build to get kernel-doc warnings? Is 
>> there a tool I can run?
>> Where is the kernel-doc format documented? I'd like to avoid this in 
>> the future.
>
> Hi,
>
> Here is the 0day bot report:
> https://lore.kernel.org/lkml/202108010650.DLRzJOtm-lkp@intel.com/
> (not sent to any of your group, sadly).
>
> kernel-doc format is documented in 
> Documentation/doc-guide/kernel-doc.rst.
>
> The 0day bot lists the reproduction steps. It used clang but I used
> gcc. Shouldn't matter in this case. The main point from the 0day bot
> is that "this is a W=1 build".  Using W=1 causes checks for extra
> C compiler warnings and also it causes checks for documentation build
> errors/warnings.
>
> In your build environment, using "make W=1 ARCH=s390 allmodconfig all"
> will produce lots of output (both compiler and kernel-doc output).
> I suppose that is the expected way to do it.
>
> AFAIK there is no support for something like "make W=1 htmldocs"
> to just check for kernel-doc errors/warnings in source files, so what
> I do when I am targeting only one source file is something like what
> is documented in the file referenced above:
>
> "Running the ``kernel-doc`` tool with increased verbosity and without 
> actual
> output generation may be used to verify proper formatting of the
> documentation comments. For example::
>
>     scripts/kernel-doc -v -none drivers/foo/bar.c
> "
> and then I script that for ease of use.
> Using the latter command reports lots more kernel-doc warnings than
> the 0day bot reported, so I fixed all of them that it found.
>
>
> HTH.
>
>
>> On 8/6/21 1:01 AM, Randy Dunlap wrote:
>>> The 0day bot reported some kernel-doc warnings in this file so clean up
>>> all of the kernel-doc and use proper kernel-doc formatting.
>>> There are no more kernel-doc errors or warnings reported in this file.
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>> Reported-by: kernel test robot <lkp@intel.com>
>>> Cc: Jason Gunthorpe <jgg@nvidia.com>
>>> Cc: Tony Krowiak <akrowiak@linux.ibm.com>
>>> Cc: Halil Pasic <pasic@linux.ibm.com>
>>> Cc: Jason Herne <jjherne@linux.ibm.com>
>>> Cc: Harald Freudenberger <freude@linux.ibm.com>
>>> Cc: linux-s390@vger.kernel.org
>>> ---
>>>   drivers/s390/crypto/vfio_ap_ops.c |  116 ++++++++++++----------------
>>>   1 file changed, 52 insertions(+), 64 deletions(-)
>
>