From a30bcb2c5146189b1bd0d9880f648616b52ae6c5 Mon Sep 17 00:00:00 2001
From: Drishti Tripathi <drishtitripathi21@gmail.com>
Date: Mon, 1 Jun 2026 10:33:02 -0700
Subject: [PATCH] PR #2069: docs: fix documentation inconsistencies in
 escaping.h

Imported from GitHub PR https://github.com/abseil/abseil-cpp/pull/2069

Fix documentation inconsistencies in absl/strings/escaping.h:

- Add missing `true` return value documentation to
  WebSafeBase64Unescape(), aligning it with the parallel
  Base64Unescape() which already documents this.

- Fix missing closing backtick in WebSafeBase64Escape() comment
  (`dest` was unterminated).

- Fix inconsistent single quotes to backticks on `src`/`dest`
  references, matching the style used elsewhere in the file.
Merge 0616be30809f4d2a1aa72450421bc87dd7631a48 into fe126c727b925b7c3b2742f6f54690973216952b

Merging this change closes #2069

COPYBARA_INTEGRATE_REVIEW=https://github.com/abseil/abseil-cpp/pull/2069 from DrishtiTripathi2230:docs/websafe-base64-unescape-return-value 0616be30809f4d2a1aa72450421bc87dd7631a48
PiperOrigin-RevId: 924786942
Change-Id: Idcd6d27e1da696614cd8c9417bb6facb277d1d47
---
 absl/strings/escaping.h | 21 +++++++++++----------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/absl/strings/escaping.h b/absl/strings/escaping.h
index aaacc289..4a23c13a 100644
--- a/absl/strings/escaping.h
+++ b/absl/strings/escaping.h
@@ -82,7 +82,7 @@ inline bool CUnescape(absl::string_view source,
 
 // CEscape()
 //
-// Escapes a 'src' string using C-style escapes sequences
+// Escapes a `src` string using C-style escapes sequences
 // (https://en.cppreference.com/w/cpp/language/escape), escaping other
 // non-printable/non-whitespace bytes as octal sequences (e.g. "\377").
 //
@@ -95,7 +95,7 @@ std::string CEscape(absl::string_view src);
 
 // CHexEscape()
 //
-// Escapes a 'src' string using C-style escape sequences, escaping
+// Escapes a `src` string using C-style escape sequences, escaping
 // other non-printable/non-whitespace bytes as hexadecimal sequences (e.g.
 // "\xFF").
 //
@@ -108,7 +108,7 @@ std::string CHexEscape(absl::string_view src);
 
 // Utf8SafeCEscape()
 //
-// Escapes a 'src' string using C-style escape sequences, escaping bytes as
+// Escapes a `src` string using C-style escape sequences, escaping bytes as
 // octal sequences, and passing through UTF-8 characters without conversion.
 // I.e., when encountering any bytes with their high bit set, this function
 // will not escape those values, whether or not they are valid UTF-8.
@@ -116,14 +116,14 @@ std::string Utf8SafeCEscape(absl::string_view src);
 
 // Utf8SafeCHexEscape()
 //
-// Escapes a 'src' string using C-style escape sequences, escaping bytes as
+// Escapes a `src` string using C-style escape sequences, escaping bytes as
 // hexadecimal sequences, and passing through UTF-8 characters without
 // conversion.
 std::string Utf8SafeCHexEscape(absl::string_view src);
 
 // Base64Escape()
 //
-// Encodes a `src` string into a base64-encoded 'dest' string with padding
+// Encodes a `src` string into a base64-encoded `dest` string with padding
 // characters. This function conforms with RFC 4648 section 4 (base64) and RFC
 // 2045.
 std::string Base64Escape(absl::string_view src);
@@ -137,7 +137,7 @@ Base64Escape(absl::string_view src, std::string* absl_nonnull dest) {
 // WebSafeBase64Escape()
 //
 // Encodes a `src` string into a base64 string, like Base64Escape() does, but
-// outputs '-' instead of '+' and '_' instead of '/', and does not pad 'dest'.
+// outputs '-' instead of '+' and '_' instead of '/', and does not pad `dest`.
 // This function conforms with RFC 4648 section 5 (base64url).
 std::string WebSafeBase64Escape(absl::string_view src);
 [[deprecated(
@@ -159,10 +159,11 @@ bool Base64Unescape(absl::string_view src, std::string* absl_nonnull dest);
 // WebSafeBase64Unescape()
 //
 // Converts a `src` string encoded in "web safe" Base64 (RFC 4648 section 5) to
-// its binary equivalent, writing it to a `dest` buffer. If `src` contains
-// invalid characters, `dest` is cleared and returns `false`. If padding is
-// included (note that `WebSafeBase64Escape()` does not produce it), it must be
-// correct. In the padding, '=' and '.' are treated identically.
+// its binary equivalent, writing it to a `dest` buffer, returning `true` on
+// success. If `src` contains invalid characters, `dest` is cleared and returns
+// `false`. If padding is included (note that `WebSafeBase64Escape()` does not
+// produce it), it must be correct. In the padding, '=' and '.' are treated
+// identically.
 bool WebSafeBase64Unescape(absl::string_view src,
                            std::string* absl_nonnull dest);