Merge branch 'wip/jtojnar/strfunc-docs' into 'main'

docs: Improve g_strescape & g_strcompress descriptions

See merge request GNOME/glib!4084

docs/reference/glib/gvariant-text-format.md

@@ -85,14 +85,14 @@ won't work and you'll end up with the individual characters corresponding to
 each byte.
 
 Unicode escapes of the form `\uxxxx` and `\Uxxxxxxxx` are supported, in
-hexadecimal. The usual control sequence escapes `\a`, `\b`, `\f`, `\n`,
+hexadecimal. The [usual control sequence escapes][C escape sequences]
-`\r`, `\t` and `\v` are supported. Additionally, a `\` before a newline
+`\a`, `\b`, `\f`, `\n`, `\r`, `\t` and `\v` are supported.
-character causes the newline to be ignored. Finally, any other character
+Additionally, a `\` before a newline character causes the newline to be ignored.
-following `\` is copied literally (for example, `\"` or `\\`) but for
+Finally, any other character following `\` is copied literally
-forwards compatibility with future additions you should only use this
+(for example, `\"` or `\\`) but for forwards compatibility with future additions
-feature when necessary for escaping backslashes or quotes.
+you should only use this feature when necessary for escaping backslashes or quotes.
 
-The usual octal and hexadecimal escapes `\0nnn` and `\xnn` are not supported
+The usual octal and hexadecimal escapes `\nnn` and `\xnn` are not supported
 here. Those escapes are used to encode byte values and `GVariant` strings
 are Unicode.
 
@@ -303,10 +303,15 @@ end with a `NUL` byte.
 Bytestrings are specified with either `b""` or `b''`. As with strings, there
 is no fundamental difference between the two different types of quotes.
 
-Bytestrings support the full range of escapes that you would expect (ie:
+Like in strings, the [C-style control sequence escapes][C escape sequences]
-those supported by [`func@GLib.strcompress`]. This includes the normal control
+`\a`, `\b`, `\f`, `\n`, `\r`, `\t` and `\v` are supported. Similarly,
-sequence escapes (as mentioned in the section on strings) as well as octal
+a `\` before a newline character causes the newline to be ignored.
-and hexadecimal escapes of the forms `\0nnn` and `\xnn`.
+Unlike in strings, you can use octal escapes of the form `\nnn`.
+Finally, any other character following `\` is copied literally
+(for example, `\"` or `\\`) but for forwards compatibility
+with future additions you should only use this feature when necessary
+for escaping backslashes or quotes. Unlike in strings, Unicode escapes
+are not supported.
 
 `b'abc'` is equivalent to `[byte 0x61, 0x62, 0x63, 0]`.
 
@@ -344,3 +349,5 @@ string to be parsed. Format strings that collect multiple arguments are
 permitted, so you may require more varargs parameters than the number of `%`
 signs that appear. You can also give format strings that collect no
 arguments, but there's no good reason to do so.
+
+[C escape sequences]: https://en.wikipedia.org/wiki/Escape_sequences_in_C#Escape_sequences

glib/gstrfuncs.c

@@ -2109,9 +2109,20 @@ g_strcanon (gchar       *string,
  * g_strcompress:
  * @source: a string to compress
  *
- * Replaces all escaped characters with their one byte equivalent.
+ * Makes a copy of a string replacing C string-style escape
+ * sequences with their one byte equivalent:
  *
- * This function does the reverse conversion of [func@GLib.strescape].
+ * - `\b` → [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace)
+ * - `\f` → [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed)
+ * - `\n` → [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline)
+ * - `\r` → [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return)
+ * - `\t` → [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character)
+ * - `\v` → [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab)
+ * - `\` followed by one to three octal digits → the numeric value (mod 255)
+ * - `\` followed by any other character → the character as is.
+ *   For example, `\\` will turn into a backslash (`\`) and `\"` into a double quote (`"`).
+ *
+ * [func@GLib.strescape] does the reverse conversion.
  *
  * Returns: a newly-allocated copy of @source with all escaped
  *   character compressed
@@ -2188,11 +2199,22 @@ out:
  * @source: a string to escape
  * @exceptions: (nullable): a string of characters not to escape in @source
  *
- * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
+ * It replaces the following special characters in the string @source
- * and '"' in the string @source by inserting a '\' before
+ * with their corresponding C escape sequence:
- * them. Additionally all characters in the range 0x01-0x1F (everything
+ *
+ *  Symbol | Escape
+ * ---|---
+ *  [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) | `\b`
+ *  [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) | `\f`
+ *  [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) | `\n`
+ *  [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) | `\r`
+ *  [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) | `\t`
+ *  [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) | `\v`
+ *
+ * It also inserts a backslash (`\`) before any backslash or a double quote (`"`).
+ * Additionally all characters in the range 0x01-0x1F (everything
  * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
- * replaced with a '\' followed by their octal representation.
+ * replaced with a backslash followed by their octal representation.
  * Characters supplied in @exceptions are not escaped.
  *
  * [func@GLib.strcompress] does the reverse conversion.

glib/gstrfuncs.h

@@ -327,21 +327,9 @@ g_strdup_inline (const char *str)
 #endif /* !defined (__GTK_DOC_IGNORE__) */
 #endif /* G_GNUC_CHECK_VERSION (2, 0) */
 
-/* Make a copy of a string interpreting C string -style escape
- * sequences. Inverse of g_strescape. The recognized sequences are \b
- * \f \n \r \t \\ \" and the octal format.
- */
 GLIB_AVAILABLE_IN_ALL
 gchar*                g_strcompress    (const gchar *source) G_GNUC_MALLOC;
 
-/* Copy a string escaping nonprintable characters like in C strings.
- * Inverse of g_strcompress. The exceptions parameter, if non-NULL, points
- * to a string containing characters that are not to be escaped.
- *
- * Deprecated API: gchar* g_strescape (const gchar *source);
- * Luckily this function wasn't used much, using NULL as second parameter
- * provides mostly identical semantics.
- */
 GLIB_AVAILABLE_IN_ALL
 gchar*                g_strescape      (const gchar *source,
 					const gchar *exceptions) G_GNUC_MALLOC;