lib/string_helpers: fix some kerneldoc warnings
Subsystems (3)
Jonathan Corbet
maintainerPATCH 1/1 lib/string_helpers: fix some kerneldoc warnings
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 <[email protected]>
--- lib/string_helpers.c | 77 +++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 37 deletions(-)
lib/string_helpers.c +40 -37
@@ -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
Signature · 1 line
2.21.0