Adding inline docs for ProfileViewConfiguration (#264)

* Adding inline docs for `ProfileViewConfiguration` * Fix docs build warnings * Format * Update Sources/GravatarUI/ProfileView/ProfileViewConfiguration.swift Co-authored-by: Pinar Olguc <[email protected]> --------- Co-authored-by: Pinar Olguc <[email protected]>
Automattic · Jun 4, 2024 · 09c4995 · 09c4995
1 parent e04d49b
commit 09c4995
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 13 deletions.
diff --git a/Sources/GravatarUI/ProfileFields/ProfileButtonBuilder.swift b/Sources/GravatarUI/ProfileFields/ProfileButtonBuilder.swift
@@ -1,8 +1,15 @@
 import UIKit
 
+/// Styles for the profile view action button.
+///
 public enum ProfileButtonStyle {
+    /// Style which provides a link to display the profile.
     case view
+    /// Style which provides a link to edit the profile.
+    /// >  Use this option only when the profile is owned by your app's authenticated user.
     case edit
+    /// Style which provides a link to crerate a new account.
+    /// > This style is automatically set when the view is configured as `claimProfile`.
     case create
 }
 

diff --git a/Sources/GravatarUI/ProfileView/BaseProfileView.swift b/Sources/GravatarUI/ProfileView/BaseProfileView.swift
@@ -340,7 +340,7 @@ open class BaseProfileView: UIView, UIContentView {
         paletteType = config.palette
         padding = config.padding
         isLoading = config.isLoading
-        avatarActivityIndicatorType = config.avatarActivityIndicatorType
+        avatarActivityIndicatorType = config.avatarConfiguration.activityIndicatorType
         delegate = config.delegate
         loadAvatar(with: config)
         if config.model != nil || config.summaryModel != nil {
@@ -351,10 +351,10 @@ open class BaseProfileView: UIView, UIContentView {
     private func loadAvatar(with config: ProfileViewConfiguration) {
         loadAvatar(
             with: config.avatarID,
-            placeholder: config.avatarPlaceholder,
-            rating: config.avatarRating,
-            defaultAvatarOption: config.defaultAvatarOption,
-            options: config.avatarSettingOptions
+            placeholder: config.avatarConfiguration.placeholder,
+            rating: config.avatarConfiguration.rating,
+            defaultAvatarOption: config.avatarConfiguration.defaultAvatarOption,
+            options: config.avatarConfiguration.settingOptions
         )
     }
 

diff --git a/Sources/GravatarUI/ProfileView/ProfileViewConfiguration.swift b/Sources/GravatarUI/ProfileView/ProfileViewConfiguration.swift
@@ -1,25 +1,45 @@
 import Gravatar
 import UIKit
 
+/// A configuration that specifies the appearance and behavior of a ProfileView and its contents.
+///
+/// You can use a configuration instance to configure a ProfileView, or to create one using `makeContentView()` method.
+///
+/// To configure a specific ProfileView style, use the static method provided to create a new configuration with the desired style:
+/// ```swift
+/// ProfileViewConfiguration.standard()     // ProfileView
+/// ProfileViewConfiguration.summary()      // ProfileSummaryView
+/// ProfileViewConfiguration.large()        // LargeProfileView
+/// ProfileViewConfiguration.largeSummary() // LargeProfileSummaryView
+/// ```
+/// After creating a configuration, you can modify any of the available fields to properly configure the profile view.
+///
 @MainActor
 public struct ProfileViewConfiguration: UIContentConfiguration {
+    /// The model used to populate the view's content.
     public var model: ProfileModel?
+    /// The model used to populate summary-styled profile views.
     public var summaryModel: ProfileSummaryModel?
+    /// The style for the profile view.
     public let profileStyle: Style
+    /// The identifier for the avatar image to be loaded in the profile view.
     var avatarID: AvatarIdentifier? {
         model?.avatarIdentifier ?? summaryModel?.avatarIdentifier
     }
 
+    /// The palette to be used to style the view.
     public var palette: PaletteType
+    /// Creates a padding space around the content of the profile view.
+    /// To remove all pading, set this to zero.
     public var padding: UIEdgeInsets = BaseProfileView.defaultPadding
+    /// Wether the state of the view is `loading`.
+    /// Set this property to `true` when the profile information is being retreived and not yet set to the profile view.
     public var isLoading: Bool = false
-    public var avatarActivityIndicatorType: ActivityIndicatorType = .activity
-    public var avatarPlaceholder: UIImage? = nil
-    public var avatarRating: Rating? = nil
-    public var defaultAvatarOption: DefaultAvatarOption? = nil
-    public var avatarSettingOptions: [ImageSettingOption]? = nil
-
+    /// A configuration to control the loading and behavior of the profile avatar.
+    public var avatarConfiguration = AvatarConfiguration()
+    /// Style of the button on the action button on the profile view.
     public var profileButtonStyle: ProfileButtonStyle = .view
+    /// The delegate will receive events from various interations of the user on the profile view.
     public weak var delegate: ProfileViewDelegate?
 
     init(model: ProfileModel?, palette: PaletteType, profileStyle: Style) {
@@ -58,35 +78,77 @@ public struct ProfileViewConfiguration: UIContentConfiguration {
 }
 
 extension ProfileViewConfiguration {
+    /// All the different style designs for the profile view.
     public enum Style: String, CaseIterable {
+        /// The configuration will create a ``ProfileView`` instance.
         case standard
+        /// The configuration will create a ``ProfileSummaryView`` instance.
         case summary
+        /// The configuration will create a ``LargeProfileView`` instance.
         case large
+        /// The configuration will create a ``LargeProfileSummaryView`` instance.
         case largeSummary
     }
 }
 
 extension ProfileViewConfiguration {
+    /// A configuration that specifies the behavior and loading options for the profile avatar.
+    public struct AvatarConfiguration {
+        /// The activity indicator used on the image view while the avatar is loading.
+        public var activityIndicatorType: ActivityIndicatorType = .activity
+        /// An image to be displayed while an avatar image has not been set.
+        public var placeholder: UIImage? = nil
+        /// The maximum rating of the avatar for it to be displayed. See `Gravatar.Rating` for more info.
+        public var rating: Rating? = nil
+        /// The avatar style to be displayed when no avatar has been found
+        /// See `Gravatar.DefaultAvatarOption` for more info.
+        public var defaultAvatarOption: DefaultAvatarOption? = nil
+        /// Options for fetchingg the avatar image. See `Gravatar.ImageSettingOption` for more info.
+        public var settingOptions: [ImageSettingOption]? = nil
+    }
+}
+
+extension ProfileViewConfiguration {
+    /// Creates a configuration set with the `standard` style.
+    /// - Parameters:
+    ///   - model: The model to be used to populate the profile view content.
+    ///   - palette: The palette to apply to the view.
+    /// - Returns: A configuration set with the standard style.
     public static func standard(model: ProfileModel? = nil, palette: PaletteType = .system) -> ProfileViewConfiguration {
         self.init(model: model, palette: palette, profileStyle: .standard)
     }
 
+    /// Creates a configuration set with the `summary` style.
+    /// - Parameters:
+    ///   - model: The model to be used to populate the profile view content.
+    ///   - palette: The palette to apply to the view.
+    /// - Returns: A configuration set with the summary style.
     public static func summary(model: ProfileSummaryModel? = nil, palette: PaletteType = .system) -> ProfileViewConfiguration {
         self.init(model: model, palette: palette, profileStyle: .summary)
     }
 
+    /// Creates a configuration set with the `large` style.
+    /// - Parameters:
+    ///   - model: The model to be used to populate the profile view content.
+    ///   - palette: The palette to apply to the view.
+    /// - Returns: A configuration set with the large style.
     public static func large(model: ProfileModel? = nil, palette: PaletteType = .system) -> ProfileViewConfiguration {
         self.init(model: model, palette: palette, profileStyle: .large)
     }
 
+    /// Creates a configuration set with the `largeSummary` style.
+    /// - Parameters:
+    ///   - model: The model to be used to populate the profile view content.
+    ///   - palette: The palette to apply to the view.
+    /// - Returns: A configuration set with the largeSummary style.
     public static func largeSummary(model: ProfileSummaryModel? = nil, palette: PaletteType = .system) -> ProfileViewConfiguration {
         self.init(model: model, palette: palette, profileStyle: .largeSummary)
     }
 
     /// Creates a `ProfileViewConfiguration` that is designed for emails without a Gravatar account. This configuration invites the user to claim their
     /// Gravatar profile.
     /// - Parameters:
-    ///   - style: Style of the profile view. See: ``ProfileViewConfiguration.Style``
+    ///   - style: Style of the profile view. See: ``Style``
     ///   - userName: Optional. If not provided, a string that says "Your Name" will be shown.
     ///   - palette: The ``PaletteType`` to use.
     /// - Returns: A new `ProfileViewConfiguration`.
@@ -108,7 +170,9 @@ extension ProfileViewConfiguration {
     private func configureAsClaim() -> ProfileViewConfiguration {
         var copy = self
         copy.profileButtonStyle = .create
-        copy.avatarPlaceholder = UIImage(named: "empty-profile-avatar")
+        var avatarConfig = AvatarConfiguration()
+        avatarConfig.placeholder = UIImage(named: "empty-profile-avatar")
+        copy.avatarConfiguration = avatarConfig
         return copy
     }
 }