From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757930AbcFHVP3 (ORCPT ); Wed, 8 Jun 2016 17:15:29 -0400 Received: from mail1.bemta8.messagelabs.com ([216.82.243.206]:58411 "EHLO mail1.bemta8.messagelabs.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755779AbcFHVOl (ORCPT ); Wed, 8 Jun 2016 17:14:41 -0400 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFjrGIsWRWlGSWpSXmKPExsVywNY2Q3dfV0S 4QXc3u8XCtiUsFpd3zWFzYPL4vEkugDGKNTMvKb8igTVj8tvZLAWPNCoOvL3G1sD4UaGLkZND SGAXo8Tcc/UQ9n5GiSvfgGwuIPsSo8T2Xd8ZIZy1jBL73yxhgXC2MEr8XP+TFaSFTcBAYuadu +wgtojAeRaJp7dyuxg5OJgF1CRufLcECQsLhEgsfNjKBmKzCKhI9H2axQhi8wp4SWxp+Q02Rk JATuLksclgNidQ/OGvtUwQF3lKtLx7zA5hq0kcPvuIDWS8hECwxMEjPBBjBCVOznzCAmIzC0h IHHzxgnkCo9AsJKlZSFILGJlWMWoUpxaVpRbpGhrpJRVlpmeU5CZm5ugaGljo5aYWFyemp+Yk JhXrJefnbmIEhi8DEOxgnDDL+RCjJAeTkihvmXtEuBBfUn5KZUZicUZ8UWlOavEhRhkODiUJ3 uROoJxgUWp6akVaZg4wkmDSEhw8SiK8J0HSvMUFibnFmekQqVOMilLivItBEgIgiYzSPLg2WP ReYpSVEuZlBDpEiKcgtSg3swRV/hWjOAejkjDvMpApPJl5JXDTXwEtZgJavPxIOMjikkSElFQ DY0Qjr7zKq3ldVzf2b1LucJxrFLpkvlDWOcvNU+Y013OvM+Y3ca7k2+KoffCtKIfm/YPaGybE 6R7nC5oV3n5vusnrPwYbDB+feXcpbOkjTcGsioXO07i2TU5Kjj39/lzjb12PpruqLutyv1kl+ IjlFCwof2Iy43KhtkBlk9WnK7aZTHE7OY3mK7EUZyQaajEXFScCAI2iJzHZAgAA X-Env-Sender: David.Kershner@unisys.com X-Msg-Ref: server-7.tower-45.messagelabs.com!1465420474!28516434!16 X-Originating-IP: [192.61.61.104] X-StarScan-Received: X-StarScan-Version: 8.46; banners=-,-,- X-VirusChecked: Checked From: David Kershner To: , , , , , , , , , , , , , , , , , , , , , CC: Tim Sell Subject: [PATCH v4 17/29] staging: unisys: visorbus: fix commenting in vbusdevinfo.h Date: Wed, 8 Jun 2016 17:14:11 -0400 Message-ID: <1465420463-24982-18-git-send-email-david.kershner@unisys.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> References: <1465420463-24982-1-git-send-email-david.kershner@unisys.com> X-OriginalArrivalTime: 08 Jun 2016 21:14:28.0966 (UTC) FILETIME=[BE3CB860:01D1C1CA] MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: David Binder 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 Signed-off-by: Tim Sell Signed-off-by: David Kershner --- 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 for bytes, and writes to - * the buffer at

, which is bytes long, ensuring never to - * overflow the buffer at

, using the following rules: - * - printable characters are simply copied from the buffer at to the - * buffer at

- * - intervening streaks of non-printable characters in the buffer at - * are replaced with a single space in the buffer at

+/** + * 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

. * - * Pass

== NULL and == 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

, 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 to an ascii decimal string - * at

, writing at most bytes. Note there is NO '\0' termination - * written to

. +/** + * 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

. + * 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 , and converts its contents to a printable string at

, - * writing at most bytes. Note there is NO '\0' termination - * written to

. +/** + * 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 >= 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

. + * Return: number of bytes written to @p */ static inline int vbuschannel_devinfo_to_string(struct ultra_vbus_deviceinfo *devinfo, -- 1.9.1