Adds documentation for stringification extension

PiperOrigin-RevId: 480166410
Change-Id: Ie915e98747ffda0d1f0e5a72383f5dd9fc940970

absl/strings/str_cat.h

@@ -77,6 +77,43 @@ struct AlphaNumBuffer {
   size_t size;
   size_t size;
 };
 };
 
 
+//------------------------------------------------------------------------------
+// StrCat Extension
+//------------------------------------------------------------------------------
+//
+// AbslStringify()
+//
+// A simple customization API for formatting user-defined types using
+// absl::StrCat(). The API relies on detecting an overload in the
+// user-defined type's namespace of a free (non-member) `AbslStringify()`
+// function as a friend definition with the following signature:
+//
+// template <typename Sink>
+// void AbslStringify(Sink& sink, const X& value);
+//
+// An `AbslStringify()` overload for a type should only be declared in the same
+// file and namespace as said type.
+//
+// Note that AbslStringify() also supports use with absl::StrFormat().
+//
+// Example:
+//
+// struct Point {
+//   // To add formatting support to `Point`, we simply need to add a free
+//   // (non-member) function `AbslStringify()`. This method specifies how
+//   // Point should be printed when absl::StrCat() is called on it. You can add
+//   // such a free function using a friend declaration within the body of the
+//   // class. The sink parameter is a templated type to avoid requiring
+//   // dependencies.
+//   template <typename Sink> friend void AbslStringify(Sink&
+//   sink, const Point& p) {
+//     absl::Format(&sink, "(%v, %v)", p.x, p.y);
+//   }
+//
+//   int x;
+//   int y;
+// };
+
 class StringifySink {
 class StringifySink {
  public:
  public:
   void Append(size_t count, char ch);
   void Append(size_t count, char ch);

absl/strings/str_format.h

@@ -570,6 +570,41 @@ ABSL_MUST_USE_RESULT inline bool FormatUntyped(
 // StrFormat Extensions
 // StrFormat Extensions
 //------------------------------------------------------------------------------
 //------------------------------------------------------------------------------
 //
 //
+// AbslStringify()
+//
+// A simpler customization API for formatting user-defined types using
+// absl::StrFormat(). The API relies on detecting an overload in the
+// user-defined type's namespace of a free (non-member) `AbslStringify()`
+// function as a friend definition with the following signature:
+//
+// template <typename Sink>
+// void AbslStringify(Sink& sink, const X& value);
+//
+// An `AbslStringify()` overload for a type should only be declared in the same
+// file and namespace as said type.
+//
+// Note that unlike with AbslFormatConvert(), AbslStringify() does not allow
+// customization of allowed conversion characters. AbslStringify() uses `%v` as
+// the underlying conversion specififer. Additionally, AbslStringify() supports
+// use with absl::StrCat while AbslFormatConvert() does not.
+//
+// Example:
+//
+// struct Point {
+//   // To add formatting support to `Point`, we simply need to add a free
+//   // (non-member) function `AbslStringify()`. This method prints in the
+//   // request format using the underlying `%v` specifier. You can add such a
+//   // free function using a friend declaration within the body of the class.
+//   // The sink parameter is a templated type to avoid requiring dependencies.
+//   template <typename Sink>
+//   friend void AbslStringify(Sink& sink, const Point& p) {
+//     absl::Format(&sink, "(%v, %v)", p.x, p.y);
+//   }
+//
+//   int x;
+//   int y;
+// };
+//
 // AbslFormatConvert()
 // AbslFormatConvert()
 //
 //
 // The StrFormat library provides a customization API for formatting
 // The StrFormat library provides a customization API for formatting
@@ -616,9 +651,9 @@ ABSL_MUST_USE_RESULT inline bool FormatUntyped(
 //   AbslFormatConvert(const Point& p, const absl::FormatConversionSpec& spec,
 //   AbslFormatConvert(const Point& p, const absl::FormatConversionSpec& spec,
 //                     absl::FormatSink* s) {
 //                     absl::FormatSink* s) {
 //     if (spec.conversion_char() == absl::FormatConversionChar::s) {
 //     if (spec.conversion_char() == absl::FormatConversionChar::s) {
-//       s->Append(absl::StrCat("x=", p.x, " y=", p.y));
+//       absl::Format(s, "x=%vy=%v", p.x, p.y);
 //     } else {
 //     } else {
-//       s->Append(absl::StrCat(p.x, ",", p.y));
+//       absl::Format(s, "%v,%v", p.x, p.y);
 //     }
 //     }
 //     return {true};
 //     return {true};
 //   }
 //   }