Add a documentation requirement to the Macro protocol

With the Macro protocol being the way in which macros are declared,
with no in-source representation, we lost the ability to have a
documentation comment. Add that back with a new (defaulted)
requirement to provide documentation.

Author: DougGregor

Sources/_SwiftSyntaxMacros/Macro.swift

@@ -16,6 +16,12 @@ public protocol Macro {
   /// The name of this macro.
   static var name: String { get }
 
+  /// Documentation for this macro.
+  ///
+  /// This documentation should be written in the Markdown format used for
+  /// commenting Swift declarations.
+  static var documentation: String { get }
+
   /// The generic signature to use when describing the type of this macro.
   static var genericSignature: GenericParameterClauseSyntax? { get }
 
@@ -28,3 +34,8 @@ public protocol Macro {
   /// semantic one.
   static var signature: TypeSyntax { get }
 }
+
+extension Macro {
+  /// Default, empty documentation string for macros.
+  public static var documentation: String { "" }
+}

Sources/_SwiftSyntaxMacros/MacroSystem+Builtin.swift

@@ -16,6 +16,10 @@ import SwiftSyntaxBuilder
 struct ColumnMacro: ExpressionMacro {
   static var name: String { "column" }
 
+  static var documentation: String {
+    "The column at which this macro is used"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByIntegerLiteral>
@@ -36,6 +40,10 @@ struct ColumnMacro: ExpressionMacro {
 struct LineMacro: ExpressionMacro {
   static var name: String { "line" }
 
+  static var documentation: String {
+    "The line at which this macro is used"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByIntegerLiteral>
@@ -68,6 +76,10 @@ extension PatternBindingSyntax {
 struct FunctionMacro: ExpressionMacro {
   static var name: String { "function" }
 
+  static var documentation: String {
+    "The name of the function in which this macro is used"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByStringLiteral>
@@ -180,6 +192,10 @@ struct FunctionMacro: ExpressionMacro {
 struct ColorLiteralMacro: ExpressionMacro {
   static var name: String { "colorLiteral" }
 
+  static var documentation: String {
+    "A color value expressed in terms of its RGBA components"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByColorLiteral>
@@ -206,6 +222,10 @@ struct ColorLiteralMacro: ExpressionMacro {
 struct FileLiteralMacro: ExpressionMacro {
   static var name: String { "fileLiteral" }
 
+  static var documentation: String {
+    "A file resource in the application bundle"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
       """
       <T: ExpressibleByFileReferenceLiteral>
@@ -228,6 +248,10 @@ struct FileLiteralMacro: ExpressionMacro {
 struct ImageLiteralMacro: ExpressionMacro {
   static var name: String { "imageLiteral" }
 
+  static var documentation: String {
+    "An image resource in the application bundle"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
       """
       <T: ExpressibleByImageLiteral>
@@ -250,6 +274,10 @@ struct ImageLiteralMacro: ExpressionMacro {
 struct FilePathMacro: ExpressionMacro {
   static var name: String { "filePath" }
 
+  static var documentation: String {
+    "The full path to the file in which this macro is used"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByStringLiteral>
@@ -274,6 +302,10 @@ struct FilePathMacro: ExpressionMacro {
 struct FileIDMacro: ExpressionMacro {
   static var name: String { "fileID" }
 
+  static var documentation: String {
+    "The file in which this macro is used in the form ModuleName/FileName"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByStringLiteral>
@@ -304,6 +336,10 @@ struct FileIDMacro: ExpressionMacro {
 struct FileMacro: ExpressionMacro {
   static var name: String { "file" }
 
+  static var documentation: String {
+    "The file in which this macro is used"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? =
      """
      <T: ExpressibleByStringLiteral>

Sources/_SwiftSyntaxMacros/MacroSystem+Examples.swift

@@ -17,6 +17,10 @@ import SwiftSyntaxBuilder
 struct StringifyMacro: ExpressionMacro {
   static var name: String { "stringify" }
 
+  static var documentation: String {
+    "An example macro that produces the value of an expression and its source text"
+  }
+
   static var genericSignature: GenericParameterClauseSyntax? = "<T>"
 
   static var signature: TypeSyntax = "(T) -> (T, String)"

Tests/SwiftSyntaxMacrosTest/MacroSystemTests.swift

@@ -140,4 +140,9 @@ final class MacroSystemTests: XCTestCase {
       """
     )
   }
+
+  func testDocumentation() {
+    let macro = MacroSystem.builtinMacroSystem.lookup("line")!
+    XCTAssertEqual(macro.documentation, "The line at which this macro is used")
+  }
 }