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=DKIMWL_WL_HIGH,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS, USER_AGENT_SANE_2 autolearn=no 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 5085BC2BA1B for ; Wed, 8 Apr 2020 16:42:16 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 2632120769 for ; Wed, 8 Apr 2020 16:42:16 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586364136; bh=dZflYwtdOE4WpeF55n3a5433aJ25TRS76smK0BBXLRc=; h=Date:From:To:Cc:Subject:In-Reply-To:References:List-ID:From; b=qBnZdJ78cHUhzbfK8VIMH4j6av3o9zTJk8oRzLqKHtl2xqh75YAEuJV/Xba3DBSBX 9tQXAMGzVVnPSuv0DpMAUovyhqs++Y/S/0PNUEQRPrp23EZvVA3u9exllak4kOSpAn 0lFPJttbDf/1HRWS18ErD5wvfhHRbHLq+rE8sKpE= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730371AbgDHQmP (ORCPT ); Wed, 8 Apr 2020 12:42:15 -0400 Received: from mail.kernel.org ([198.145.29.99]:44848 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730369AbgDHQmP (ORCPT ); Wed, 8 Apr 2020 12:42:15 -0400 Received: from coco.lan (ip5f5ad4d8.dynamic.kabel-deutschland.de [95.90.212.216]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 7CC9420769; Wed, 8 Apr 2020 16:42:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1586364134; bh=dZflYwtdOE4WpeF55n3a5433aJ25TRS76smK0BBXLRc=; h=Date:From:To:Cc:Subject:In-Reply-To:References:From; b=pX91x5p/ex8/LllfJiIeej2SPjWU/d1wcD7IAD90y5SaEHcvFWXo85xGJ6QFBMt1u ZiJGS26q3FFxWcH4/RHQQO1EgOWg5eAFYZtiHFCUXlkUkUnqv1soXL7RpTyJsVE5zd k0B9JNAg2QY85+hKcn3mTGujmOGS6djP0timfAgw= Date: Wed, 8 Apr 2020 18:42:10 +0200 From: Mauro Carvalho Chehab To: Mark Brown Cc: Linux Doc Mailing List , linux-kernel@vger.kernel.org, Jonathan Corbet , linux-spi@vger.kernel.org Subject: Re: [PATCH 21/35] docs: spi: spi.h: fix a doc building warning Message-ID: <20200408184210.43c4411b@coco.lan> In-Reply-To: <20200408161629.GC5177@sirena.org.uk> References: <20200408154925.GA5177@sirena.org.uk> <20200408181154.6c290772@coco.lan> <20200408161629.GC5177@sirena.org.uk> X-Mailer: Claws Mail 3.17.5 (GTK+ 2.24.32; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-doc-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-doc@vger.kernel.org Em Wed, 8 Apr 2020 17:16:29 +0100 Mark Brown escreveu: > On Wed, Apr 08, 2020 at 06:11:54PM +0200, Mauro Carvalho Chehab wrote: > > Mark Brown escreveu: > > > > Are you sure this is a sensible fix? The following lines should be part > > > of the documentation for transfer_one, will that be the case after your > > > change? > > > Without that, Sphinx will warn and may produce something unexpected. > > Right, but if the warning is telling us something useful we want to > handle it rather than just shutting it up. True. Without adding the blank line, kernel-doc would output this as: ``transfer_one`` transfer a single spi_transfer. - return 0 if the transfer is finished, - return 1 if the transfer is still in progress. When the driver is finished with this transfer it must call spi_finalize_current_transfer() so the subsystem can issue the next transfer. Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the generic subsystem does not call your transfer_one callback. This would be parsed by Sphinx (newer versions) as if the second line: transfer a single spi_transfer. would be a sort of subtitle that should be highlighted with a vertical line before that. E. g. something equivalent to: ============ |transfer_one| ------------------------------- |transfer a single spi_transfer.| - return 0 if the transfer is finished, - return 1 if the transfer is still in progress. When the driver is finished with this transfer it must call spi_finalize_current_transfer() so the subsystem can issue the next transfer. Note: transfer_one and transfer_one_message are mutually exclusive; when both are set, the generic subsystem does not call your transfer_one callback. Which is not the desired result. Adding a blank line after it fixes the issue, making it produce the expected output. > > > If this patch is applied after 20/25, the output should produce the > > correct result: > > > https://www.infradead.org/~mchehab/kernel_docs/driver-api/spi.html#spi-master-methods > > OK. > > Acked-by: Mark Brown Thanks, Mauro