3 files changed, 16 insertions, 5 deletions
diff --git a/absl/strings/str_cat.h b/absl/strings/str_cat.h
index 559ee0aa..a99aac01 100644
--- a/absl/strings/str_cat.h
+++ b/absl/strings/str_cat.h
@@ -37,7 +37,8 @@
 // attempt to pass ':' instead of ":" might result in a 58 ending up in your
 // result.
 //
-// Bools convert to "0" or "1".
+// Bools convert to "0" or "1". Pointers to types other than `char *` are not
+// valid inputs. No output is generated for null `char *` pointers.
 //
 // Floating point numbers are formatted with six-digit precision, which is
 // the default for "std::cout <<" or printf "%g" (the same as "%.6g").
diff --git a/absl/strings/str_format.h b/absl/strings/str_format.h
index da3208e1..0b93c288 100644
--- a/absl/strings/str_format.h
+++ b/absl/strings/str_format.h
@@ -20,7 +20,8 @@
 // The `str_format` library is a typesafe replacement for the family of
 // `printf()` string formatting routines within the `<cstdio>` standard library
 // header. Like the `printf` family, the `str_format` uses a "format string" to
-// perform argument substitutions based on types.
+// perform argument substitutions based on types. See the `FormatSpec` section
+// below for format string documentation.
 //
 // Example:
 //
@@ -67,6 +68,7 @@
 // In addition, the `str_format` library provides extension points for
 // augmenting formatting to new types. These extensions are fully documented
 // within the `str_format_extension.h` header file.
+
 #ifndef ABSL_STRINGS_STR_FORMAT_H_
 #define ABSL_STRINGS_STR_FORMAT_H_
 
@@ -211,6 +213,11 @@ class FormatCountCapture {
 //     written to this point. The resulting value must be captured within an
 //     `absl::FormatCountCapture` type.
 //
+// Implementation-defined behavior:
+//   * A null pointer provided to "%s" or "%p" is output as "(nil)".
+//   * A non-null pointer provided to "%p" is output in hex as if by %#x or
+//     %#lx.
+//
 // NOTE: `o`, `x\X` and `u` will convert signed values to their unsigned
 // counterpart before formatting.
 //
@@ -226,7 +233,7 @@ class FormatCountCapture {
 //     "%e", .01                -> "1.00000e-2"
 //     "%a", -3.0               -> "-0x1.8p+1"
 //     "%g", .01                -> "1e-2"
-//     "%p", *int               -> "0x7ffdeb6ad2a4"
+//     "%p", (void*)&value      -> "0x7ffdeb6ad2a4"
 //
 //     int n = 0;
 //     std::string s = absl::StrFormat(
diff --git a/absl/strings/substitute.h b/absl/strings/substitute.h
index 32dec30b..233e9dcf 100644
--- a/absl/strings/substitute.h
+++ b/absl/strings/substitute.h
@@ -35,10 +35,13 @@
 // and single digit positional ids to indicate which substitution arguments to
 // use at that location within the format string.
 //
+// A '$$' sequence in the format string causes a literal '$' character to be
+// output.
+//
 // Example 1:
-//   std::string s = Substitute("$1 purchased $0 $2. Thanks $1!",
+//   std::string s = Substitute("$1 purchased $0 $2 for $$10. Thanks $1!",
 //                              5, "Bob", "Apples");
-//   EXPECT_EQ("Bob purchased 5 Apples. Thanks Bob!", s);
+//   EXPECT_EQ("Bob purchased 5 Apples for $10. Thanks Bob!", s);
 //
 // Example 2:
 //   std::string s = "Hi. ";