Tightened the source code and README documentations in the library.

Sources/PlaydateKit/Sound/Signal/Classes/Signal.swift

@@ -1,8 +1,8 @@
 internal import CPlaydate
 
 extension Sound {
-    /// A signal object; also provides custom signals driven by Swift
-    /// callbacks. Wraps `PDSynthSignal`.
+    /// A scaled, offset signal: custom (Swift callbacks) or tracking another value.
+    /// Wraps `PDSynthSignal`.
     public final class Signal: SignalValue {
         private static var api: UnsafePointer<playdate_sound_signal> { Playdate.signalAPI.unsafelyUnwrapped }
 
@@ -11,7 +11,7 @@ extension Sound {
             init(_ callbacks: Callbacks) { self.callbacks = callbacks }
         }
 
-        /// Creates a signal driven by the given callbacks.
+        /// `callbacks` stay alive until the C signal is freed.
         public init(callbacks: Callbacks) {
             let box = Unmanaged.passRetained(Box(callbacks))
             let pointer = Signal.api.pointee.newSignal.unsafelyUnwrapped(
@@ -38,8 +38,7 @@ extension Sound {
             super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
         }
 
-        /// Creates a plain signal object wrapping an existing signal value,
-        /// so it can be scaled and offset.
+        /// Tracks `value` so it can be scaled and offset; does not keep `value` alive.
         public init(value: SignalValue) {
             let pointer = Signal.api.pointee.newSignalForValue.unsafelyUnwrapped(value.pointer)
             super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
@@ -55,17 +54,15 @@ extension Sound {
             }
         }
 
-        /// The signal's current value.
         public var value: Float {
             Signal.api.pointee.getValue.unsafelyUnwrapped(pointer)
         }
 
-        /// Scales the signal's output.
+        /// Applied before the offset.
         public func setValueScale(_ scale: Float) {
             Signal.api.pointee.setValueScale.unsafelyUnwrapped(pointer, scale)
         }
 
-        /// Offsets the signal's output.
         public func setValueOffset(_ offset: Float) {
             Signal.api.pointee.setValueOffset.unsafelyUnwrapped(pointer, offset)
         }