Message-ID: <1465420463-24982-18-git-send-email-david.kershner@unisys.com>
Date:	Wed, 8 Jun 2016 17:14:11 -0400
From:	David Kershner <david.kershner@...sys.com>
To:	<corbet@....net>, <tglx@...utronix.de>, <mingo@...hat.com>,
	<hpa@...or.com>, <david.kershner@...sys.com>,
	<gregkh@...uxfoundation.org>, <erik.arfvidson@...sys.com>,
	<timothy.sell@...sys.com>, <hofrat@...dl.org>,
	<dzickus@...hat.com>, <jes.sorensen@...hat.com>,
	<alexander.curtin@...sys.com>, <janani.rvchndrn@...il.com>,
	<sudipm.mukherjee@...il.com>, <prarit@...hat.com>,
	<david.binder@...sys.com>, <nhorman@...hat.com>,
	<dan.j.williams@...el.com>, <linux-kernel@...r.kernel.org>,
	<linux-doc@...r.kernel.org>,
	<driverdev-devel@...uxdriverproject.org>,
	<sparmaintainer@...sys.com>
CC:	Tim Sell <Timothy.Sell@...sys.com>
Subject: [PATCH v4 17/29] staging: unisys: visorbus: fix commenting in vbusdevinfo.h

From: David Binder <david.binder@...sys.com>

This patch ONLY touches comment lines, i.e., NO executable code is
affected.

* All functions worthy of documenting now use standard kerneldoc
  formatting.
* Multi-line comments were tweaked so as to use appropriate conventions.
* Minor typos were corrected.

Signed-off-by: David Binder <david.binder@...sys.com>
Signed-off-by: Tim Sell <Timothy.Sell@...sys.com>
Signed-off-by: David Kershner <david.kershner@...sys.com>
---
 drivers/staging/unisys/visorbus/vbusdeviceinfo.h | 65 ++++++++++++++++--------
 1 file changed, 43 insertions(+), 22 deletions(-)

diff --git a/drivers/staging/unisys/visorbus/vbusdeviceinfo.h b/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
index abdab4a..e6bfed1 100644
--- a/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
+++ b/drivers/staging/unisys/visorbus/vbusdeviceinfo.h
@@ -19,7 +19,8 @@
 
 #pragma pack(push, 1)		/* both GCC and VC now allow this pragma */
 
-/* An array of this struct is present in the channel area for each vbus.
+/*
+ * An array of this struct is present in the channel area for each vbus.
  * (See vbuschannel.h.)
  * It is filled in by the client side to provide info about the device
  * and driver from the client's perspective.
@@ -34,19 +35,28 @@ struct ultra_vbus_deviceinfo {
 
 #pragma pack(pop)
 
-/* Reads chars from the buffer at <src> for <srcmax> bytes, and writes to
- * the buffer at <p>, which is <remain> bytes long, ensuring never to
- * overflow the buffer at <p>, using the following rules:
- * - printable characters are simply copied from the buffer at <src> to the
- *   buffer at <p>
- * - intervening streaks of non-printable characters in the buffer at <src>
- *   are replaced with a single space in the buffer at <p>
+/**
+ * vbuschannel_sanitize_buffer() - remove non-printable chars from buffer
+ * @p: destination buffer where chars are written to
+ * @remain: number of bytes that can be written starting at #p
+ * @src: pointer to source buffer
+ * @srcmax: number of valid characters at #src
+ *
+ * Reads chars from the buffer at @src for @srcmax bytes, and writes to
+ * the buffer at @p, which is @remain bytes long, ensuring never to
+ * overflow the buffer at @p, using the following rules:
+ * - printable characters are simply copied from the buffer at @src to the
+ *   buffer at @p
+ * - intervening streaks of non-printable characters in the buffer at @src
+ *   are replaced with a single space in the buffer at @p
  * Note that we pay no attention to '\0'-termination.
- * Returns the number of bytes written to <p>.
  *
- * Pass <p> == NULL and <remain> == 0 for this special behavior.  In this
+ * Pass @p == NULL and @remain == 0 for this special behavior -- In this
  * case, we simply return the number of bytes that WOULD HAVE been written
- * to a buffer at <p>, had it been infinitely big.
+ * to a buffer at @p, had it been infinitely big.
+ *
+ * Return: the number of bytes written to @p (or WOULD HAVE been written to
+ *         @p, as described in the previous paragraph)
  */
 static inline int
 vbuschannel_sanitize_buffer(char *p, int remain, char *src, int srcmax)
@@ -92,14 +102,18 @@ vbuschannel_sanitize_buffer(char *p, int remain, char *src, int srcmax)
 		p++;  chars++;  remain--;	   \
 	} while (0)
 
-/* Converts the non-negative value at <num> to an ascii decimal string
- * at <p>, writing at most <remain> bytes.  Note there is NO '\0' termination
- * written to <p>.
+/**
+ * vbuschannel_itoa() - convert non-negative int to string
+ * @p: destination string
+ * @remain: max number of bytes that can be written to @p
+ * @num: input int to convert
+ *
+ * Converts the non-negative value at @num to an ascii decimal string
+ * at @p, writing at most @remain bytes.  Note there is NO '\0' termination
+ * written to @p.
  *
- * Returns the number of bytes written to <p>.
+ * Return: number of bytes written to @p
  *
- * Note that we create this function because we need to do this operation in
- * an environment-independent way (since we are in a common header file).
  */
 static inline int
 vbuschannel_itoa(char *p, int remain, int num)
@@ -141,13 +155,20 @@ vbuschannel_itoa(char *p, int remain, int num)
 	return digits;
 }
 
-/* Reads <devInfo>, and converts its contents to a printable string at <p>,
- * writing at most <remain> bytes.  Note there is NO '\0' termination
- * written to <p>.
+/**
+ * vbuschannel_devinfo_to_string() - format a struct ultra_vbus_deviceinfo
+ *                                   to a printable string
+ * @devinfo: the struct ultra_vbus_deviceinfo to format
+ * @p: destination string area
+ * @remain: size of destination string area in bytes
+ * @devix: the device index to be included in the output data, or -1 if no
+ *         device index is to be included
  *
- * Pass <devix> >= 0 if you want a device index presented.
+ * Reads @devInfo, and converts its contents to a printable string at @p,
+ * writing at most @remain bytes. Note there is NO '\0' termination
+ * written to @p.
  *
- * Returns the number of bytes written to <p>.
+ * Return: number of bytes written to @p
  */
 static inline int
 vbuschannel_devinfo_to_string(struct ultra_vbus_deviceinfo *devinfo,
-- 
1.9.1

Powered by blists - more mailing lists