Adjust component documentation

danielsaidi · Feb 15, 2024 · 035c5d6 · 035c5d6
1 parent 5f5bc29
commit 035c5d6
Show file tree

Hide file tree

Showing 13 changed files with 65 additions and 61 deletions.
diff --git a/Sources/RichTextKit/Commands/RichTextCommand+ShareMenu.swift b/Sources/RichTextKit/Commands/RichTextCommand+ShareMenu.swift
@@ -95,9 +95,13 @@ public extension RichTextCommand {
 
 private extension RichTextCommand.ShareMenu {
 
-    var hasExportFormats: Bool { !exportFormats.isEmpty }
+    var hasExportFormats: Bool {
+        !exportFormats.isEmpty
+    }
 
-    var hasShareFormats: Bool { !shareFormats.isEmpty }
+    var hasShareFormats: Bool {
+        !shareFormats.isEmpty
+    }
 }
 
 private extension RichTextCommand.ShareMenu {

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Alignment.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Alignment.swift
@@ -3,7 +3,7 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-05-29.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
@@ -16,21 +16,17 @@ import AppKit
 
 public extension RichTextViewComponent {
 
-    /// Get the rich text alignment at current range.
+    /// Get the text alignment at the current range.
     var richTextAlignment: RichTextAlignment? {
         guard let style = richTextParagraphStyle else { return nil }
         return RichTextAlignment(style.alignment)
     }
 
-    /// Set the rich text alignment at current range.
-    ///
-    /// This function does not use ``RichTextAttributeWriter``
-    /// since the text views require affecting text storage.
+    /// Set the text alignment at the current range.
     ///
     /// > Important: This function will affect the next line
-    /// of text if we grab `richTextParagraphStyle` and make
-    /// the alignment change to it, instead of creating this
-    /// brand new paragraph style.
+    /// if it changes the `richTextParagraphStyle` value, so
+    /// it instead creates a brand new paragraph style.
     func setRichTextAlignment(
         _ alignment: RichTextAlignment
     ) {

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Attributes.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Attributes.swift
@@ -3,14 +3,14 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-05-29.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
 
 public extension RichTextViewComponent {
 
-    /// Get all rich text attributes at current range.
+    /// Get all attributes at the current range.
     var richTextAttributes: RichTextAttributes {
         if hasSelectedRange {
             return richTextAttributes(at: selectedRange)
@@ -25,14 +25,14 @@ public extension RichTextViewComponent {
         #endif
     }
 
-    /// Get a certain rich text attribute at current range.
+    /// Get a certain attribute at the current range.
     func richTextAttribute<Value>(
         _ attribute: RichTextAttribute
     ) -> Value? {
         richTextAttributes[attribute] as? Value
     }
 
-    /// Set a certain rich text attribute at current range.
+    /// Set a certain attribute at the current range.
     func setRichTextAttribute(
         _ attribute: RichTextAttribute,
         to value: Any
@@ -44,8 +44,10 @@ public extension RichTextViewComponent {
         }
     }
 
-    /// Set certain attributes at current range.
-    func setRichTextAttributes(_ attributes: RichTextAttributes) {
+    /// Set certain attributes at the current range.
+    func setRichTextAttributes(
+        _ attributes: RichTextAttributes
+    ) {
         attributes.forEach { attribute, value in
             setRichTextAttribute(attribute, to: value)
         }

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Colors.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Colors.swift
@@ -3,22 +3,22 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-05-30.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
 
 public extension RichTextViewComponent {
 
-    /// Get a certain rich text color at current range.
+    /// Get a certain color at the current range.
     func richTextColor(
         _ color: RichTextColor
     ) -> ColorRepresentable? {
         guard let attribute = color.attribute else { return nil }
         return richTextAttribute(attribute)
     }
 
-    /// Get a certain rich text color at a certain range.
+    /// Get a certain color at a certain range.
     func richTextColor(
         _ color: RichTextColor,
         at range: NSRange
@@ -27,7 +27,7 @@ public extension RichTextViewComponent {
         return richTextAttribute(attribute, at: range)
     }
 
-    /// Set a certain rich text color at current range.
+    /// Set a certain color at the current range.
     func setRichTextColor(
         _ color: RichTextColor,
         to val: ColorRepresentable
@@ -37,7 +37,7 @@ public extension RichTextViewComponent {
         setRichTextAttribute(attribute, to: val)
     }
 
-    /// Set a certain rich text color at a certain range.
+    /// Set a certain colors at a certain range.
     func setRichTextColor(
         _ color: RichTextColor,
         to val: ColorRepresentable,

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Font.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Font.swift
@@ -7,7 +7,8 @@
 //
 
 /// These functions may seem complicated, but it is the only
-/// way that seems to work correctly, so far.
+/// way that seems to work correctly, so far. Perhaps it can
+/// be simplified in 1.0, after removing all deprecated code.
 ///
 /// I previously grabbed the `typingAttributes` and took the
 /// `.font` attribute from it, then took its `fontDescriptor`

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Images.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Images.swift
@@ -3,7 +3,7 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-06-05.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
@@ -18,7 +18,7 @@ import AppKit
 
 public extension RichTextViewComponent {
 
-    /// Get the attachment max size for a certain image.
+    /// Get the max image attachment size.
     var imageAttachmentMaxSize: CGSize {
         let maxSize = imageConfiguration.maxImageSize
         let insetX = 2 * textContentInset.width
@@ -40,7 +40,9 @@ public extension RichTextViewComponent {
     }
 
     /// Get the attachment size for a certain image.
-    func attachmentSize(for image: ImageRepresentable) -> CGSize {
+    func attachmentSize(
+        for image: ImageRepresentable
+    ) -> CGSize {
         attributedString.attachmentSize(
             for: image,
             maxSize: imageAttachmentMaxSize

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Indent.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Indent.swift
@@ -27,7 +27,6 @@ public extension RichTextViewComponent {
     ///
     /// Unlike some other attributes, this attribute applies
     /// to the entire paragraph, not just the selected range.
-    /// It therefore needs special treatment.
     func stepRichTextIndent(
         points: CGFloat
     ) {

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Paragraph.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Paragraph.swift
@@ -18,7 +18,7 @@ import AppKit
 
 public extension RichTextViewComponent {
 
-    /// Get the rich text paragraph style at current range.
+    /// Get the paragraph style at the current range.
     var richTextParagraphStyle: NSMutableParagraphStyle? {
         richTextAttribute(.paragraphStyle)
     }

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Pasting.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Pasting.swift
@@ -3,7 +3,7 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-06-05.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
@@ -19,12 +19,13 @@ import AppKit
 public extension RichTextViewComponent {
 
     /**
-     Paste an image into the text view, at a certain index.
+     Paste an image into the rich text, at a certain index.
 
-     For now, pasting will automatically insert the image as
-     a compressed jpeg. We should expand this to allow us to
-     define format, compression etc. For now, it's hardcoded
-     and a future TODO.
+     Pasting images only works on iOS, tvOS and macOS. Other
+     platform will trigger an assertion failure.
+     
+     > Todo: This automatically inserts images as compressed
+     jpeg. We should make it more configurable.
 
      - Parameters:
        - image: The image to paste.
@@ -47,9 +48,12 @@ public extension RichTextViewComponent {
 
     /**
      Paste images into the text view, at a certain index.
+     
+     This will automatically insert an image as a compressed
+     jpeg. We should make it more configurable.
 
-     Pasting images only works on iOS, tvOS and macOS. Other
-     platform will trigger an assertion failure.
+     > Todo: This automatically inserts images as compressed
+     jpeg. We should make it more configurable.
 
      - Parameters:
        - images: The images to paste.

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Ranges.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Ranges.swift
@@ -2,7 +2,7 @@
 //  RichTextViewComponent+Ranges.swift
 //  RichTextKit
 //
-//  Created by Daniel Saidi on 2024-02-14.
+//  Created by Dominik Bucher
 //
 
 import Foundation

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Styles.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Styles.swift
@@ -3,14 +3,14 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-05-29.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
 
 public extension RichTextViewComponent {
 
-    /// Get all rich text styles at current range.
+    /// Get all styles at the current range.
     var richTextStyles: [RichTextStyle] {
         let attributes = richTextAttributes
         let traits = richTextFont?.fontDescriptor.symbolicTraits
@@ -25,7 +25,7 @@ public extension RichTextViewComponent {
         richTextStyles.contains(style)
     }
 
-    /// Set a certain rich text style at current range.
+    /// Set a certain style at the current range.
     func setRichTextStyle(
         _ style: RichTextStyle,
         to newValue: Bool
@@ -45,7 +45,7 @@ public extension RichTextViewComponent {
         }
     }
 
-    /// Set a certain rich text style at current range.
+    /// Toggle a certain style at the current range.
     func toggleRichTextStyle(
         _ style: RichTextStyle
     ) {

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent+Superscript.swift b/Sources/RichTextKit/Component/RichTextViewComponent+Superscript.swift
@@ -2,15 +2,15 @@
 //  RichTextViewComponent+Color.swift
 //  RichTextKit
 //
-//  Created by Daniel Saidi on 2022-05-30.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Created by Daniel Saidi on 2024-02-14.
+//  Copyright © 2024 Daniel Saidi. All rights reserved.
 //
 
 import Foundation
 
 public extension RichTextViewComponent {
 
-    /// Get the rich text superscript level at current range.
+    /// Get the superscript level at the current range.
     var richTextSuperscriptLevel: Int? {
         #if macOS
         richTextAttribute(.superscript)
@@ -19,7 +19,7 @@ public extension RichTextViewComponent {
         #endif
     }
 
-    /// Set the rich text superscript level at current range.
+    /// Set the superscript level at the current range.
     func setRichTextSuperscriptLevel(to val: Int) {
         #if macOS
         setRichTextAttribute(.superscript, to: val)
@@ -28,7 +28,7 @@ public extension RichTextViewComponent {
         #endif
     }
 
-    /// Step the rich text font size at current range.
+    /// Step the superscript level at the current range.
     func stepRichTextSuperscriptLevel(points: Int) {
         let currentSize = richTextSuperscriptLevel ?? 0
         let newSize = currentSize + points

diff --git a/Sources/RichTextKit/Component/RichTextViewComponent.swift b/Sources/RichTextKit/Component/RichTextViewComponent.swift
@@ -3,7 +3,7 @@
 //  RichTextKit
 //
 //  Created by Daniel Saidi on 2022-05-22.
-//  Copyright © 2022-2023 Daniel Saidi. All rights reserved.
+//  Copyright © 2022-2024 Daniel Saidi. All rights reserved.
 //
 
 import CoreGraphics
@@ -17,18 +17,18 @@ import AppKit
 
 
 /**
- This protocol defines a platform-agnostic api that's shared
- by the UIKit and AppKit ``RichTextView`` components.
+ This protocol provides a common interface for the UIKit and
+ AppKit ``RichTextView`` components.
 
- By implementing and using this protocol in the library, the
- library doesn't have to do a bunch of `#if` checks.
+ By implementing this protocol, the library does not have to
+ do a bunch of `#if` platform checks within the code.
+ 
+ This component can read and write many different attributes
+ from and to its rich text, using the underlying features of
+ ``RichTextAttributeReader`` and ``RichTextAttributeWriter``.
 
  The protocol implements and extends many other protocols to
  provide more features for components with more capabilities.
-
- The protocol for instance extends ``RichTextAttributeReader``
- and ``RichTextAttributeWriter`` and adds new functions that
- don't require a `range`, since it can use the current range.
  */
 public protocol RichTextViewComponent: AnyObject,
     RichTextPresenter,
@@ -52,9 +52,6 @@ public protocol RichTextViewComponent: AnyObject,
     var isFirstResponder: Bool { get }
 
     /// The text view's layout manager, if any.
-    ///
-    /// This is optional and renamed since UIKit will have a
-    /// non-otional manager and AppKit an optional one.
     var layoutManagerWrapper: NSLayoutManager? { get }
 
     /// The text view's mutable attributed string, if any.
@@ -64,9 +61,6 @@ public protocol RichTextViewComponent: AnyObject,
     var textContentInset: CGSize { get set }
 
     /// The text view's text storage, if any.
-    ///
-    /// This is optional and renamed since UIKit will have a
-    /// non-otional storage and AppKit an optional one.
     var textStorageWrapper: NSTextStorage? { get }
 
     /// The text view current typing attributes.
@@ -81,6 +75,7 @@ public protocol RichTextViewComponent: AnyObject,
         format: RichTextDataFormat
     )
 
+
     // MARK: - Functions
 
     /// Show an alert with a title, message and button text.
@@ -105,6 +100,7 @@ public protocol RichTextViewComponent: AnyObject,
     func undoLatestChange()
 }
 
+
 // MARK: - Public Extension
 
 public extension RichTextViewComponent {