Added docs for object hook methods

Author: lukaskubanek

Sources/InterposeKit/Interpose.swift

@@ -129,6 +129,50 @@ public enum Interpose {
     // MARK: Object Hooks
     // ============================================================================ //
 
+    /// Prepares a hook for the specified method on an object.
+    ///
+    /// Builds a block-based hook for an instance method available to the Objective-C runtime,
+    /// with access to the original implementation.
+    ///
+    /// The hook is returned in a pending state and must be applied using `apply()` to take effect.
+    /// It can then be reverted using `revert()`.
+    ///
+    /// InterposeKit installs the hook by creating a dynamic subclass at runtime and assigning it
+    /// to the object. This ensures the hook only affects this specific object and leaves all other
+    /// instances unchanged.
+    ///
+    /// - Parameters:
+    ///   - object: The object on which to hook the method.
+    ///   - selector: The selector of the method to hook.
+    ///   - methodSignature: The expected C function type of the original method implementation.
+    ///   - hookSignature: The type of the hook block.
+    ///   - build: A closure that receives a proxy to the hook and returns the hook block.
+    ///
+    /// - Returns: The prepared hook instance in the pending state.
+    ///
+    /// - Throws: An ``InterposeError`` if the hook could not be prepared.
+    ///
+    /// ### Example
+    ///
+    /// ```swift
+    /// let object = MyClass()
+    /// let hook = try Interpose.prepareHook(
+    ///     on: object,
+    ///     for: #selector(MyClass.getValue),
+    ///     methodSignature: (@convention(c) (MyClass, Selector) -> Int).self,
+    ///     hookSignature: (@convention(block) (MyClass) -> Int).self
+    /// ) { hook in
+    ///     return { `self` in
+    ///         print("Before")
+    ///         let value = hook.original(self, hook.selector)
+    ///         print("After")
+    ///         return value + 1
+    ///     }
+    /// }
+    ///
+    /// try hook.apply()
+    /// try hook.revert()
+    /// ```
     public static func prepareHook<MethodSignature, HookSignature>(
         on object: NSObject,
         for selector: Selector,
@@ -143,6 +187,48 @@ public enum Interpose {
         )
     }
 
+    /// Applies a hook for the specified method on an object.
+    ///
+    /// Builds a block-based hook for an instance method available to the Objective-C runtime,
+    /// with access to the original implementation.
+    ///
+    /// The hook takes effect immediately and can later be reverted using `revert()`.
+    ///
+    /// InterposeKit installs the hook by creating a dynamic subclass at runtime and assigning it
+    /// to the object. This ensures the hook only affects this specific object and leaves all other
+    /// instances unchanged.
+    ///
+    /// - Parameters:
+    ///   - object: The object on which to hook the method.
+    ///   - selector: The selector of the method to hook.
+    ///   - methodSignature: The expected C function type of the original method implementation.
+    ///   - hookSignature: The type of the hook block.
+    ///   - build: A closure that receives a proxy to the hook and returns the hook block.
+    ///
+    /// - Returns: The applied hook instance in the active state.
+    ///
+    /// - Throws: An ``InterposeError`` if the hook could not be applied.
+    ///
+    /// ### Example
+    ///
+    /// ```swift
+    /// let object = MyClass()
+    /// let hook = try Interpose.applyHook(
+    ///     on: object,
+    ///     for: #selector(MyClass.getValue),
+    ///     methodSignature: (@convention(c) (MyClass, Selector) -> Int).self,
+    ///     hookSignature: (@convention(block) (MyClass) -> Int).self
+    /// ) { hook in
+    ///     return { `self` in
+    ///         print("Before")
+    ///         let value = hook.original(self, hook.selector)
+    ///         print("After")
+    ///         return value + 1
+    ///     }
+    /// }
+    ///
+    /// try hook.revert()
+    /// ```
     @discardableResult
     public static func applyHook<MethodSignature, HookSignature>(
         on object: NSObject,