[PATCH] spi: bcm2835: Add missing kernel-doc Return sections

[Tomasz Unger]

scripts/kernel-doc -Wall reports two functions in this file with no
description of their return value:

  bcm2835_spi_prepare_sg()
  bcm2835_spi_transfer_one_dma()

bcm2835_spi_prepare_sg() already describes its return value, but in a
"Return 0 on success ..." sentence that kernel-doc does not recognize.
Convert it to a "Return:" section.

bcm2835_spi_transfer_one_dma() has no description at all. It returns 1
once the DMA transfer has been started, which tells the SPI core that
the transfer is still in progress and will be finalized later by
spi_finalize_current_transfer() from the DMA completion callbacks, or a
negative error number. Document that.

No functional change.

Signed-off-by: Tomasz Unger <tomasz.unger@xxxxxxxx>
---
 drivers/spi/spi-bcm2835.c | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/drivers/spi/spi-bcm2835.c b/drivers/spi/spi-bcm2835.c
index cc5748973281..8d4456bbe572 100644
--- a/drivers/spi/spi-bcm2835.c
+++ b/drivers/spi/spi-bcm2835.c
@@ -666,7 +666,8 @@ static void bcm2835_spi_dma_tx_done(void *data)
  * @is_tx: whether to submit DMA descriptor for TX or RX sglist
  *
  * Prepare and submit a DMA descriptor for the TX or RX sglist of @tfr.
- * Return 0 on success or a negative error number.
+ *
+ * Return: 0 on success or a negative error number.
  */
 static int bcm2835_spi_prepare_sg(struct spi_controller *ctlr,
 				  struct spi_transfer *tfr,
@@ -766,6 +767,10 @@ static int bcm2835_spi_prepare_sg(struct spi_controller *ctlr,
  * has finished, the DMA engine zero-fills the TX FIFO until it is half full.
  * (Tuneable with the DC register.)  So up to 9 gratuitous bus accesses are
  * performed at the end of an RX-only transfer.
+ *
+ * Return: 1 if the transfer was started and is still in progress, in which
+ * case it is finalized from the DMA completion callbacks, or a negative error
+ * number.
  */
 static int bcm2835_spi_transfer_one_dma(struct spi_controller *ctlr,
 					struct spi_transfer *tfr,

---
base-commit: 6628e7d4c6b25c8d18f1345e3a20d21829aae7e4
change-id: 20261110-spi-bcm2835-kdoc-return-65e2d032b331

Best regards,
--  
Tomasz Unger <tomasz.unger@xxxxxxxx>