From patchwork Fri Jun 7 17:09:52 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jonathan Corbet X-Patchwork-Id: 166177 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp895858ili; Fri, 7 Jun 2019 10:09:57 -0700 (PDT) X-Google-Smtp-Source: APXvYqxH7v17pBTHX0dT8qeCEMb5FSHDkbmjEx+P3UA3GbtBZOGZQT2VgYxuNAaEHzq53W5dTH6e X-Received: by 2002:a63:35c8:: with SMTP id c191mr3798306pga.171.1559927397345; Fri, 07 Jun 2019 10:09:57 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1559927397; cv=none; d=google.com; s=arc-20160816; b=gflpwaIqx6CY8PDVWTUBsnqfiepeV7DXI08ri+aulRTdqbdYCWSGu5mClCaZE6N88K 3xU8uecSEkbJiQQZoKOdZvu4uppd/j3pmNjNVUuJEbopWkI7Q3w1oDcV4xybOsW6ZE0b ysYHv2Lk8i6nLCsWXCxO1dNj6SI4kWfO3wS7m5vOu42W+L/QjK6TIUcOuUNPwKsujiKS 7nf+0bktaShjm39zp0WmcOrRKsouPRvtl2A2OZtTjFaFCwPc3TBLmd/i47GwzrcyuvJV Epg0IOpU9TBx9wyqr63hp//VcVdgQzX7Xe82NLUoDPLI5I7c9889FVIoYOextuu8nm1i R8KA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :organization:message-id:subject:cc:to:from:date; bh=NNyFKGdHm5UeJOtQAiSSuPs0vlO7WuqlSB2T7py/XXI=; b=XccqpVv/Ea9iBSXREeRL+BOlsmTx6mZAlDVMSKsvxC6SRJ2TVrJvtaps4c9XTEtXsU 4xJ0+LMWXA6zKyRxVJcFVgp4jhvM0koj5Q2nY19FoSwMXKQUo0tTKDoUiMuVpemOwwFo vFR1ok0TiH1ilTftDnSNzew+ZCJsSkFeGJ5q33wNiAO4MLiXD5gdLbhrKswBjYEvTROl hXcy0j/TRDv0WrDyTVGrn/qwiZP7a44mGOsMf1cH/Xl18TOcja9FfJ77ga7bQG6Ns1fa VNKDp8wQ3ULX3eBJna3QCYQ5dExheGw1oSqc81zBmJxaEc+uuMnXwomyLKNuGAnmlXyS 39JQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id n16si2372982plp.111.2019.06.07.10.09.57; Fri, 07 Jun 2019 10:09:57 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1731251AbfFGRJ4 (ORCPT + 30 others); Fri, 7 Jun 2019 13:09:56 -0400 Received: from ms.lwn.net ([45.79.88.28]:57672 "EHLO ms.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730196AbfFGRJy (ORCPT ); Fri, 7 Jun 2019 13:09:54 -0400 Received: from lwn.net (localhost [127.0.0.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id C756A737; Fri, 7 Jun 2019 17:09:53 +0000 (UTC) Date: Fri, 7 Jun 2019 11:09:52 -0600 From: Jonathan Corbet To: Andrew Morton Cc: LKML , linux-doc@vger.kernel.org Subject: [PATCH] lib/string_helpers: fix some kerneldoc warnings Message-ID: <20190607110952.409011ba@lwn.net> Organization: LWN.net MIME-Version: 1.0 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Due to some sad limitations in how kerneldoc comments are parsed, the documentation in lib/string_helpers.c generates these warnings: ./lib/string_helpers.c:236: WARNING: Unexpected indentation. ./lib/string_helpers.c:241: WARNING: Block quote ends without a blank line; unexpected unindent. ./lib/string_helpers.c:446: WARNING: Unexpected indentation. ./lib/string_helpers.c:451: WARNING: Block quote ends without a blank line; unexpected unindent. ./lib/string_helpers.c:474: WARNING: Unexpected indentation. Rework the comments to obtain something like the desired result. Signed-off-by: Jonathan Corbet --- lib/string_helpers.c | 77 +++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 37 deletions(-) -- 2.21.0 diff --git a/lib/string_helpers.c b/lib/string_helpers.c index 29c490e5d478..a9f5ef9289e6 100644 --- a/lib/string_helpers.c +++ b/lib/string_helpers.c @@ -230,35 +230,36 @@ static bool unescape_special(char **src, char **dst) * @src: source buffer (escaped) * @dst: destination buffer (unescaped) * @size: size of the destination buffer (0 to unlimit) - * @flags: combination of the flags (bitwise OR): - * %UNESCAPE_SPACE: + * @flags: combination of the flags. + * + * Description: + * The function unquotes characters in the given string. + * + * Because the size of the output will be the same as or less than the size of + * the input, the transformation may be performed in place. + * + * Caller must provide valid source and destination pointers. Be aware that + * destination buffer will always be NULL-terminated. Source string must be + * NULL-terminated as well. The supported flags are:: + * + * UNESCAPE_SPACE: * '\f' - form feed * '\n' - new line * '\r' - carriage return * '\t' - horizontal tab * '\v' - vertical tab - * %UNESCAPE_OCTAL: + * UNESCAPE_OCTAL: * '\NNN' - byte with octal value NNN (1 to 3 digits) - * %UNESCAPE_HEX: + * UNESCAPE_HEX: * '\xHH' - byte with hexadecimal value HH (1 to 2 digits) - * %UNESCAPE_SPECIAL: + * UNESCAPE_SPECIAL: * '\"' - double quote * '\\' - backslash * '\a' - alert (BEL) * '\e' - escape - * %UNESCAPE_ANY: + * UNESCAPE_ANY: * all previous together * - * Description: - * The function unquotes characters in the given string. - * - * Because the size of the output will be the same as or less than the size of - * the input, the transformation may be performed in place. - * - * Caller must provide valid source and destination pointers. Be aware that - * destination buffer will always be NULL-terminated. Source string must be - * NULL-terminated as well. - * * Return: * The amount of the characters processed to the destination buffer excluding * trailing '\0' is returned. @@ -440,7 +441,29 @@ static bool escape_hex(unsigned char c, char **dst, char *end) * @isz: source buffer size * @dst: destination buffer (escaped) * @osz: destination buffer size - * @flags: combination of the flags (bitwise OR): + * @flags: combination of the flags + * @only: NULL-terminated string containing characters used to limit + * the selected escape class. If characters are included in @only + * that would not normally be escaped by the classes selected + * in @flags, they will be copied to @dst unescaped. + * + * Description: + * The process of escaping byte buffer includes several parts. They are applied + * in the following sequence. + * + * 1. The character is matched to the printable class, if asked, and in + * case of match it passes through to the output. + * 2. The character is not matched to the one from @only string and thus + * must go as-is to the output. + * 3. The character is checked if it falls into the class given by @flags. + * %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any + * character. Note that they actually can't go together, otherwise + * %ESCAPE_HEX will be ignored. + * + * Caller must provide valid source and destination pointers. Be aware that + * destination buffer will not be NULL-terminated, thus caller have to append + * it if needs. The supported flags are:: + * * %ESCAPE_SPACE: (special white space, not space itself) * '\f' - form feed * '\n' - new line @@ -463,26 +486,6 @@ static bool escape_hex(unsigned char c, char **dst, char *end) * all previous together * %ESCAPE_HEX: * '\xHH' - byte with hexadecimal value HH (2 digits) - * @only: NULL-terminated string containing characters used to limit - * the selected escape class. If characters are included in @only - * that would not normally be escaped by the classes selected - * in @flags, they will be copied to @dst unescaped. - * - * Description: - * The process of escaping byte buffer includes several parts. They are applied - * in the following sequence. - * 1. The character is matched to the printable class, if asked, and in - * case of match it passes through to the output. - * 2. The character is not matched to the one from @only string and thus - * must go as-is to the output. - * 3. The character is checked if it falls into the class given by @flags. - * %ESCAPE_OCTAL and %ESCAPE_HEX are going last since they cover any - * character. Note that they actually can't go together, otherwise - * %ESCAPE_HEX will be ignored. - * - * Caller must provide valid source and destination pointers. Be aware that - * destination buffer will not be NULL-terminated, thus caller have to append - * it if needs. * * Return: * The total size of the escaped output that would be generated for