[Debugging] Expand DebugDescriptionMacro docstring (#71700)

Describe more details of `DebugDescriptionMacro`.

Author: kastiglione

stdlib/public/core/DebuggerSupport.swift

@@ -15,15 +15,23 @@ import SwiftShims
 // Macros are disabled when Swift is built without swift-syntax.
 #if $Macros && hasAttribute(attached)
 
-/// Converts description definitions to a debugger type summary.
+/// Converts description definitions to a debugger Type Summary.
 ///
-/// This macro converts compatible `debugDescription` (or `description`)
-/// implementations to a debugger type summary. This improves debugging in
-/// situations where expression evaluation is not performed, such as the
+/// This macro converts compatible description implementations written in Swift
+/// to an LLDB format known as a Type Summary. A Type Summary is LLDB's
+/// equivalent to `debugDescription`, with the distinction that it does not
+/// execute code inside the debugged process. By avoiding code execution,
+/// descriptions can be produced faster, without potential side effects, and
+/// shown in situations where code execution is not performed, such as the
 /// variable list of an IDE.
 ///
-/// For example, this code allows the debugger to display strings such as
-/// "Rams [11-2]" without invoking `debugDescription`:
+/// Consider this an example. This `Team` struct has a `debugDescription` which
+/// summarizes some key details, such as the team's name. The debugger only
+/// computes this string on demand - typically via the `po` command. By applying
+/// the `DebugDescription` macro, a matching Type Summary is constructed. This
+/// allows the user to show a string like "Rams [11-2]", without executing
+/// `debugDescription`. This improves the usability, performance, and
+/// reliability of the debugging experience.
 ///
 ///     @DebugDescription
 ///     struct Team: CustomDebugStringConvertible {
@@ -34,6 +42,28 @@ import SwiftShims
 ///            "\(name) [\(wins)-\(losses)]"
 ///        }
 ///     }
+///
+/// The `DebugDescription` macro supports both `debugDescription`, `description`,
+/// as well as a third option: a property named `_debugDescription`. The first
+/// two are implemented when conforming to the `CustomDebugStringConvertible`
+/// and `CustomStringConvertible` protocols. The additional `_debugDescription`
+/// property is useful when both `debugDescription` and `description` are
+/// implemented, but don't meet the requirements of the `DebugDescription`
+/// macro. If `_debugDescription` is implemented, `DebugDescription` choose it
+/// over `debugDescription` and `description`. Likewise, `debugDescription` is
+/// preferred over `description`.
+///
+/// ### Description Requirements
+///
+/// The description implementation has the following requirements:
+///
+/// * The body of the description implementation must a single string
+///   expression. String concatenation is not supported, use string interpolation
+///   instead.
+/// * String interpolation can reference stored properties only, functions calls
+///   and other arbitrary computation are not supported. Of note, conditional
+///   logic and computed properties are not supported.
+/// * Overloaded string interpolation cannot be used.
 @available(SwiftStdlib 5.11, *)
 @attached(memberAttribute)
 public macro _DebugDescription() =