Merge AddDocc into main

Author: ShenghaiWang

Package.resolved

@@ -1,5 +1,23 @@
 {
   "pins" : [
+    {
+      "identity" : "swift-docc-plugin",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-plugin",
+      "state" : {
+        "revision" : "26ac5758409154cc448d7ab82389c520fa8a8247",
+        "version" : "1.3.0"
+      }
+    },
+    {
+      "identity" : "swift-docc-symbolkit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-docc-symbolkit",
+      "state" : {
+        "revision" : "b45d1f2ed151d057b54504d653e0da5552844e34",
+        "version" : "1.0.0"
+      }
+    },
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",

Package.swift

@@ -14,6 +14,7 @@ let package = Package(
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-syntax.git", from: "509.0.0-swift-5.9-DEVELOPMENT-SNAPSHOT-2023-04-25-b"),
+        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.1.0"),
     ],
     targets: [
         .macro(

README.md

@@ -6,17 +6,17 @@ A practical collection of Swift Macros that help code correctly and swiftly.
 
     .package(url: "https://github.com/ShenghaiWang/SwiftMacros.git", from: "1.0.0")
 
-## Macros
+## Macros [API Doc](https://shenghaiwang.github.io/swiftmacros/documentation/swiftmacros/)
 
 | Macro | Description  |
 |------------|------------------------------------------------------------|
 | @Access    |An easy API to access UserDefaults, NSCache and NSMapTable. |
 |            |<pre>struct TestAccess {<br>    static let cache = NSCache<NSString, AnyObject>()<br><br>    // Please make sure the generic type is the same as the type of the variable<br>    // Without defalut value<br>    @Access<Bool?>(.userDefaults())<br>    var isPaidUser: Bool?<br><br>    // With default value<br>    @Access< Bool>(.userDefaults())<br>    var isPaidUser2: Bool = false<br><br>    @Access<NSObject?>(.nsCache(TestAccess.cache))<br>    var hasPaid: NSObject?<br><br>    @Access<NSObject?>(.nsMapTable(TestAccess.mapTable))<br>    var hasPaid2: NSObject?<br>}</pre>|
 |@AddAssociatedValueVariable|Add variables to retrieve the associated values|
 |    |<pre>@AddAssociatedValueVariable<br>enum MyEnum {<br>    case first<br>    case second(Int)<br>    case third(String, Int)<br>    case forth(a: String, b: Int), forth2(String, Int)<br>    case fifth(() -> Void)<br>}</pre>|
-| @AddPublisher |Generate a Combine publisher to a Combine subject so that we can have a limited ACL for the subject |
+| @AddInit      |Generate initialiser for the class/struct/actor. The variables with optional types will have nil as default values. Using `withMock: true` if want to generate mock data. <br> For custmoised data type, it will use `Type.mock`. In case there is no this value, need to define this yourself or use `@Mock` or `@AddInit(withMock: true)` to generate this variable. |
+| @AddPublisher |Generate a Combine publisher to a Combine subject in order to avoid overexposing subject variable |
 |               |<pre>@AddPublisher<br>private let mySubject = PassthroughSubject<Void, Never>()</pre>|
-| @AddInit      |Generate initialiser for the class/struct/actor. the variables with optional types will have nil as default values. Using `withMock: true` if want to generate mock data. <br> For custmoised data type, it will use `Type.mock`. In case there is no this value, need to define this yourself or use `@Mock` or `@AddInit(withMock: true)` to generate this variable. |
 |               |<pre>@AddInit<br>struct InitStruct {<br>    let a: Int<br>    let b: Int?<br>    let c: (Int?) -> Void<br>    let d: ((Int?) -> Void)?<br>}<br>@AddInit(withMock: true)<br>class AStruct {<br>    let a: Float<br>}</pre>|
 | #buildDate    |Build a Date from components<br>This solution addes in a resultBulder `DateBuilder`, which can be used directly if prefer builder pattern.<br>Note: this is for a simpler API. Please use it with caution in places that require efficiency.|
 |            |<pre>let date = #buildDate(DateString("03/05/2003", dateFormat: "MM/dd/yyyy"),<br>                      Date(),<br>                      Month(10),<br>                      Year(1909),<br>                      YearForWeekOfYear(2025))</pre>|

Sources/Client/main.swift

@@ -22,6 +22,11 @@ struct TestStruct: Codable {
     var name = "Tim Wang"
 }
 
+@Singleton
+struct A {
+
+}
+
 let data = try #encode(TestStruct(), dateEncodingStrategy: .iso8601, dataEncodingStrategy: .base64)
 let value = try #decode(TestStruct.self, from: data, dateDecodingStrategy: .deferredToDate)
 
@@ -48,7 +53,7 @@ struct InitStruct {
     let d: ((Int?) -> Void)?
 }
 
-@AddInit
+@AddInit(withMock: true)
 actor InitActor {
     let a: Int
     let b: Int?
@@ -65,6 +70,11 @@ enum MyEnum {
     case seventh(() -> Void)
 }
 
+@AddAssociatedValueVariable
+ enum TestEnum {
+    case test(Int)
+}
+
 assert(MyEnum.first.forth2Value == nil)
 
 let url = #buildURL("http://google.com",

Sources/Macros/AddInit.swift

@@ -89,6 +89,8 @@ extension SimpleTypeIdentifierSyntax {
         guard let type = self.as(SimpleTypeIdentifierSyntax.self)?.name.text else { return nil }
         if let fun = mockFunctions[type] {
             return fun(randomValue)
+        } else if name.text == "Void" {
+            return "return"
         } else if name.text != "Set" {
             return "\(type).mock"
         }

Sources/SwiftMacros/AccessContentType.swift

@@ -1,7 +1,13 @@
 import Foundation
 
 public enum AccessContentType {
+    /// Retrieve value from or store value to [UserDefault](https://developer.apple.com/documentation/foundation/userdefaults).
+    /// Default to [.standard](https://developer.apple.com/documentation/foundation/userdefaults/1416603-standard).
     case userDefaults(UserDefaults = .standard)
+    /// Retrieve value from or store value to [NSCache](https://developer.apple.com/documentation/foundation/nscache).
+    /// Have to provide an instance of **<NSString, AnyObject>**.
     case nsCache(NSCache<NSString, AnyObject>)
+    /// Retrieve value from or store value to [NSMAPTable](https://developer.apple.com/documentation/foundation/nsmaptable)
+    /// Have to provide an instance of **NSMapTable<NSString, AnyObject>**.
     case nsMapTable(NSMapTable<NSString, AnyObject>)
 }

Sources/SwiftMacros/SwiftMacros.docc/Resources/documentation-art/macro-icon.png

@@ -0,0 +1,35 @@
+#  ``SwiftMacros``
+
+A practical collection of Swift Macros that help code correctly and swiftly.
+
+@Metadata {
+    @PageImage(purpose: icon, source: "macro-icon",  alt: "Swift-Macros")
+    @PageColor(green)
+}
+
+## Overview
+
+This collection of Swift Macros aims to remove boilerplate code by automatically generating needed code for a rich set of purposes.
+
+## Topics
+
+### Macros
+
+- ``Access(_:)``
+- ``AddAssociatedValueVariable``
+- ``AddInit(withMock:randomMockValue:)``
+- ``AddPublisher``
+- ``buildDate(_:)``
+- ``buildURL(_:)``
+- ``buildURLRequest(_:)``
+- ``encode(_:outputFormatting:dateEncodingStrategy:dataEncodingStrategy:nonConformingFloatEncodingStrategy:keyEncodingStrategy:userInfo:)``
+- ``decode(_:from:dateDecodingStrategy:dataDecodingStrategy:nonConformingFloatDecodingStrategy:keyDecodingStrategy:userInfo:allowsJSON5:assumesTopLevelDictionary:)``
+- ``formatDate(_:dateStyle:timeStyle:formattingContext:formatterBehavior:doesRelativeDateFormatting:amSymbol:pmSymbol:weekdaySymbols:shortWeekdaySymbols:veryShortWeekdaySymbols:standaloneWeekdaySymbols:shortStandaloneWeekdaySymbols:veryShortStandaloneWeekdaySymbols:monthSymbols:shortMonthSymbols:veryShortMonthSymbols:standaloneMonthSymbols:shortStandaloneMonthSymbols:veryShortStandaloneMonthSymbols:quarterSymbols:shortQuarterSymbols:standaloneQuarterSymbols:shortStandaloneQuarterSymbols:eraSymbols:longEraSymbols:)``
+- ``formatDateComponents(fromComponents:allowedUnits:allowsFractionalUnits:calendar:collapsesLargestUnit:includesApproximationPhrase:includesTimeRemainingPhrase:maximumUnitCount:unitsStyle:zeroFormattingBehavior:formattingContext:referenceDate:)``
+- ``formatDateComponents(from:to:allowedUnits:allowsFractionalUnits:calendar:collapsesLargestUnit:includesApproximationPhrase:includesTimeRemainingPhrase:maximumUnitCount:unitsStyle:zeroFormattingBehavior:formattingContext:referenceDate:)``
+- ``formatDateComponents(fromInterval:allowedUnits:allowsFractionalUnits:calendar:collapsesLargestUnit:includesApproximationPhrase:includesTimeRemainingPhrase:maximumUnitCount:unitsStyle:zeroFormattingBehavior:formattingContext:referenceDate:)``
+- ``formatDateInterval(from:to:dateStyle:timeStyle:dateTemplate:calendar:locale:timeZone:)``
+- ``Mock(type:randomMockValue:)``
+- ``postNotification(_:object:userInfo:from:)``
+- ``Singleton``
+