Improve documentation readability (#178)

Removes extra jargon and wordiness from documentation.

Author: rauhul

Sources/MMIO/Documentation.docc/Advanced-Topics/Custom-BitFieldProjectable.md

@@ -6,14 +6,14 @@ Define projections to map hardware bit fields to meaningful Swift types.
 
 When working with memory-mapped hardware registers, you're fundamentally manipulating raw bits. However, these bits often represent meaningful concepts: a single bit might indicate an enabled/disabled state, a 2-bit field might represent one of four operating modes, or a multi-bit field might encode a complex configuration.
 
-Swift MMIO provides **type projections** through the ``MMIO/BitFieldProjectable`` protocol, allowing you to map raw bit patterns to semantically meaningful Swift types. While Swift MMIO includes built-in projections for common types like `Bool` and integer types, creating your own custom projections offers several key benefits:
+Swift MMIO provides **type projections** through the ``MMIO/BitFieldProjectable`` protocol, allowing you to map raw bit patterns to semantically meaningful Swift types. Swift MMIO includes built-in projections for common types like `Bool` and integer types and creating your own custom projections lets you:
 
-- **Improved type safety**: Replace magic numbers with strongly-typed values
-- **Better code readability**: Express hardware states with meaningful names
-- **Compile-time validation**: Catch errors at compile time rather than runtime
-- **Domain-specific abstractions**: Model hardware concepts using appropriate Swift types
+- Replace magic numbers with strongly-typed values
+- Express hardware states with meaningful names
+- Catch errors at compile time rather than runtime
+- Model hardware concepts using appropriate Swift types
 
-This article guides you through creating custom types that conform to ``MMIO/BitFieldProjectable``, enabling you to represent hardware bit fields in a way that's both safer and more expressive.
+This article walks through creating custom types that conform to ``MMIO/BitFieldProjectable``.
 
 ### Understanding the BitFieldProjectable protocol
 
@@ -41,7 +41,7 @@ static var bitWidth: Int { get }
 
 This property defines how many bits your type occupies in the hardware register. This value must **exactly match** the width of the physical bit field as defined in your register macro (e.g., `bits: 4..<6` is 2 bits wide).
 
-A mismatch between your type's `bitWidth` and the actual bit field width will cause a runtime trap when accessing the register. This is a safety feature that ensures your type accurately represents the hardware's capabilities.
+A mismatch between your type's `bitWidth` and the actual bit field width causes a runtime trap when accessing the register. This safety feature ensures your type accurately represents the hardware's capabilities.
 
 #### Converting from storage
 
@@ -69,7 +69,7 @@ This method converts your type back to a raw integer value for writing to the ha
 2. Places these bits at the correct position in the register value
 3. Writes the complete register value to hardware
 
-The returned value must only use bits up to `Self.bitWidth` or will cause a runtime trap when written. The method should accurately represent your type's state in the bit pattern expected by the hardware
+The returned value must only use bits up to `Self.bitWidth` or will cause a runtime trap when written. Make sure it accurately represents your type's state in the bit pattern the hardware expects.
 
 ### Projecting an enum
 
@@ -201,7 +201,7 @@ Finally, let's add a factory method that creates values matching our "off" patte
 
 ```swift
 struct FanSpeed: BitFieldProjectable, RawRepresentable {
-    // ... 
+    // ...
 
     static func off(rawValue: UInt8 = 0b00) -> Self {
         let value = Self(rawValue: rawValue)
@@ -251,7 +251,7 @@ fanControl.modify { view in
 }
 ```
 
-This approach gives us tremendous flexibility. We can represent specific named values for common states, while also handling bit patterns with "don't care" bits. The custom pattern matching allows us to check if a value matches a particular pattern, ignoring bits that don't affect functionality.
+This approach gives us great flexibility. We can represent specific named values for common states while also handling bit patterns with "don't care" bits. The custom pattern matching lets us check if a value matches a pattern, ignoring bits that don't affect functionality.
 
 The real power of this technique becomes apparent when working with hardware that has complex bit field semantics. For example, many hardware peripherals use bit patterns where:
 - Some bits are reserved and must be zero

Sources/MMIO/Documentation.docc/Advanced-Topics/Safety-Considerations.md

@@ -4,57 +4,57 @@ Understand Swift MMIO's guarantees and developer responsibilities.
 
 ## Overview
 
-Swift MMIO improves the safety and ergonomics of memory-mapped I/O operations compared to traditional low-level programming in languages like C. However, direct hardware interaction inherently involves aspects that require careful attention from you. This article discusses the safety model and performance characteristics of Swift MMIO.
+Swift MMIO is safer and more ergonomic than traditional low-level programming in C. However, direct hardware interaction still requires careful attention. This article covers Swift MMIO's safety model and what you're responsible for.
 
 ### Developer responsibilities
 
-While Swift MMIO introduces significant safety improvements, certain aspects remain inherently unsafe due to the nature of direct hardware interaction. You are responsible for:
+Swift MMIO provides significant safety improvements, but direct hardware interaction has inherent risks. You're responsible for:
 
 1.  **Correct Base Addresses (`unsafeAddress`):**
     Providing the correct base memory address for a `RegisterBlock` or ``MMIO/Register`` is critical. An incorrect address can lead to accessing unintended memory, wrong peripherals, system faults, or data corruption. Always verify addresses against official hardware documentation.
 
 2.  **Accurate Register Layout Definitions:**
-    Definitions for ``MMIO/Register(bitWidth:)`` types (total `bitWidth`, field offsets, widths, access types via macros like ``MMIO/ReadWrite(bits:as:)``) must precisely match hardware documentation. Mismatched layouts can cause misinterpretation of status, incorrect control signals, or unintended modification of adjacent fields/registers. Use tools like `SVD2Swift` with vendor/community-vetted SVD files where possible to reduce manual errors.
+    ``MMIO/Register(bitWidth:)`` definitions (total `bitWidth`, field offsets, widths, access types via macros like ``MMIO/ReadWrite(bits:as:)``) must match hardware documentation exactly. Mismatched layouts cause misinterpreted status, incorrect control signals, or unintended modification of adjacent fields/registers. Use `SVD2Swift` with vendor/community-vetted SVD files when possible to reduce manual errors.
 
 3.  **Understanding Hardware Side Effects:**
-    MMIO register access can have side effects (e.g., read-to-clear flags, initiating time-consuming operations, state-dependent access permissions, timing requirements). Ignoring these can lead to missed events, incorrect state transitions, or hardware errors. Consult datasheets for side effects and manage them in your logic (e.g., polling, interrupt handlers, delays). Swift MMIO ensures volatile memory access but not the logical consequences of that access.
+    MMIO register access can have side effects (read-to-clear flags, triggering operations, state-dependent permissions, timing requirements). Ignoring these leads to missed events, incorrect state transitions, or hardware errors. Consult datasheets for side effects and handle them in your code (polling, interrupt handlers, delays). Swift MMIO ensures volatile memory access but can't guarantee logical correctness.
 
 ### Library responsibilities
 
 Swift MMIO offers several safety layers:
 
 1.  **Type Safety:**
-    Type projections (via ``MMIO/BitFieldProjectable``) allow bit fields to be represented by strong Swift types, preventing out-of-range/meaningless integer assignments.
+    Type projections (via ``MMIO/BitFieldProjectable``) represent bit fields as strong Swift types, preventing out-of-range or meaningless integer assignments.
 
 2.  **Compile-Time Boundary Checking for Fields:**
     Bit field definitions are checked at compile-time to be within their parent ``MMIO/Register(bitWidth:)``'s `bitWidth`.
 
 3.  **Runtime Checks for Field Access:**
-    Writing a values too large for a field's width triggers a runtime trap, preventing unintentional modification of adjacent bits.
+    Writing values too large for a field's width triggers a runtime trap, preventing unintentional modification of adjacent bits.
 
 4.  **Volatile Access Guarantee:**
     All ``MMIO/Register`` operations use volatile memory semantics, preventing incorrect compiler optimizations for MMIO. See <doc:Volatile-Access>.
 
 5.  **Reduced Boilerplate and Manual Bit Manipulation:**
-    Bit field macros automatically generate the necessary code for bit masking and shifting, avoiding common errors found in manual bitwise manipulation.
+    Bit field macros generate code for bit masking and shifting automatically, avoiding common manual bitwise manipulation errors.
 
 6.  **Clear Access Semantics:**
     Bit field macros document intended access patterns and influence the generated API (e.g., no setter for projected `ReadOnly` fields in `Write` view).
 
 7.  **Prevention of Unintended Read-Modify-Write Cycles:**
-    - Swift MMIO's API design, particularly the ``MMIO/Register/modify(_:)`` method, helps prevent a common pitfall found in C-style MMIO access. In C, using a `volatile` pointer to a struct with bitfields, code like:
+    - Swift MMIO's API design, particularly ``MMIO/Register/modify(_:)``, prevents a common pitfall in C-style MMIO access. In C, using a `volatile` pointer to a struct with bitfields like this:
       ```c
       // C example of potential unintended multiple RMWs
       volatile MyRegisterType* myReg = (MyRegisterType*)0x40001000;
       myReg->fieldA = 1; // Could be one RMW operation
       myReg->fieldB = 2; // Could be another RMW operation
       ```
-      can inadvertently result in two distinct read-modify-write sequences on the hardware register. This happens because each assignment to a bitfield member is a separate load of the entire register, modification of the relevant bits, and a store of the entire register. Such multiple RMWs can cause glitches if hardware requires fields to be updated simultaneously or can lead to incorrect behavior if the register state changes between the operations.
+      can inadvertently trigger two distinct read-modify-write sequences on the hardware register. Each bitfield assignment is a separate load of the entire register, modification of the relevant bits, and store back. Multiple RMWs cause glitches if hardware requires simultaneous field updates or lead to incorrect behavior if register state changes between operations.
     - Swift MMIO's `modify` operation avoids this. When you write:
       ```swift
       myRegister.modify { view in
           view.fieldA = valueA
           view.fieldB = valueB
       }
       ```
-      Swift MMIO performs a single volatile read of the entire register before the closure, allows modifications to an in-memory representation within the closure, and then performs a single volatile write of the combined result after the closure. This ensures that `fieldA` and `fieldB` (and any other fields modified within the closure) are updated in the hardware as part of one coherent register write.
+      Swift MMIO performs a single volatile read before the closure, allows modifications to an in-cpu-memory representation inside the closure, then performs a single volatile write after. This ensures `fieldA` and `fieldB` (and all other register fields) are updated in hardware as one coherent register write.

Sources/MMIO/Documentation.docc/Advanced-Topics/Testing-With-Interposers.md

@@ -10,9 +10,9 @@ Testing code that interacts with hardware registers presents unique challenges.
 - Specialized debugging equipment
 - Complex setup procedures to create specific hardware states
 
-These requirements make unit testing hardware-dependent code slow, expensive, and difficult to automate. Yet verifying that your code correctly interacts with hardware registers is crucial for reliable embedded systems.
+These requirements make unit testing hardware-dependent code slow, expensive, and difficult to automate. Verifying correct register interaction is crucial for reliable embedded systems.
 
-Swift MMIO addresses this challenge with **interposers**. An interposer intercepts memory operations that would normally target hardware registers. Instead of accessing physical memory, operations on ``MMIO/Register`` instances are redirected to methods on your custom interposer object. This redirection allows you to:
+Swift MMIO addresses this with **interposers**. An interposer intercepts memory operations that would normally target hardware registers. Instead of accessing physical memory, operations on ``MMIO/Register`` instances are redirected to methods on your custom interposer object. With interposers, you can:
 
 - Test register interaction logic without actual hardware
 - Verify sequences of register reads and writes
@@ -30,8 +30,8 @@ To create an interposer, define a class that conforms to the ``MMIO/MMIOInterpos
 
 Start by creating a basic interposer that simulates memory by storing values in a dictionary. This interposer:
 1. Maps memory addresses to values
-2. Returns stored values when registers are read
-3. Updates stored values when registers are written
+2. Returns stored values on reads
+3. Updates stored values on writes
 
 First, define the class structure and storage:
 
@@ -41,7 +41,7 @@ import MMIOInterposable // Use this target for interposer-enabled builds
 class BasicInterposer: MMIOInterposer {
     // Simulated memory storage - maps addresses to values
     private var memory: [UInt: UInt64] = [:]
-    
+
     // Protocol methods will be implemented next
 }
 ```
@@ -73,7 +73,7 @@ Then, implement the `store` method. This method is called whenever code writes t
 ```swift
 class BasicInterposer: MMIOInterposer {
     // ...
-    
+
     func store<Value: FixedWidthInteger & UnsignedInteger & _RegisterStorage>(
         _ value: Value, to pointer: UnsafeMutablePointer<Value>
     ) {
@@ -121,7 +121,7 @@ Next, create the tracing interposer class:
 class TracingInterposer: MMIOInterposer {
     // Record of all register accesses
     var trace: [MMIOTraceEvent] = []
-    
+
     // Simulated memory storage
     private var simulatedMemory: [UInt: UInt64] = [:]
 }
@@ -132,16 +132,16 @@ Now, implement the `load` method to record read operations. This method performs
 ```swift
 class TracingInterposer: MMIOInterposer {
     // ...
-    
+
     func load<Value: FixedWidthInteger & UnsignedInteger & _RegisterStorage>(
         from pointer: UnsafePointer<Value>
     ) -> Value {
         let address = UInt(bitPattern: pointer)
         let value = simulatedMemory[address, default: 0]
-        
+
         // Record this read operation in the trace
         trace.append(MMIOTraceEvent(type: .load, address: address, value: value))
-        
+
         return Value(value)
     }
 }
@@ -152,16 +152,16 @@ Finally, implement the `store` method to record write operations. This method al
 ```swift
 class TracingInterposer: MMIOInterposer {
     // ...
-    
+
     func store<Value: FixedWidthInteger & UnsignedInteger & _RegisterStorage>(
         _ value: Value, to pointer: UnsafeMutablePointer<Value>
     ) {
         let address = UInt(bitPattern: pointer)
         let storedValue = UInt64(value)
-        
+
         // Update simulated memory
         simulatedMemory[address] = storedValue
-        
+
         // Record this write operation in the trace
         trace.append(MMIOTraceEvent(type: .store, address: address, value: storedValue))
     }
@@ -194,10 +194,10 @@ import Testing
 struct ControlRegister {
     @ReadWrite(bits: 0..<1, as: Bool.self)
     var enable: ENABLE
-    
+
     @ReadWrite(bits: 1..<3)
     var mode: MODE
-    
+
     @ReadWrite(bits: 3..<8)
     var prescaler: PRESCALER
 }
@@ -229,22 +229,22 @@ Finally, write a test that verifies the function works correctly. The test:
    - Then, it should write the updated value with (binary 00100001 = decimal 33):
      - enable=true
      - mode=2
-     - prescaler=4 
+     - prescaler=4
 
 ```swift
 struct ControlRegisterTests {
     @Test func testUpdateWhenDisabled() throws {
         let interposer = TracingInterposer() // 1
-        
+
         let control = ControlRegister(unsafeAddress: 0x40000000, interposer: interposer) // 2
-        
+
         updateControlRegister(control, newMode: 2) // 3
-        
+
         let expectedTrace = [
             MMIOTraceEvent(type: .load, address: 0x40000000, value: 0), // 4
             MMIOTraceEvent(type: .store, address: 0x40000000, value: 33) // 4
         ]
-        
+
         #expect(interposer.trace == expectedTrace) // 4
     }
 }