Merge pull request #75 from swiftwasm/katei/documentation

Documentation and reduce number of public APIs

Sources/Spectest/TestCase.swift

@@ -546,8 +546,6 @@ extension Swift.Error {
                 return "data count and data section have inconsistent lengths"
             case .expectedRefType:
                 return "malformed reference type"
-            case .unexpectedContent:
-                return "unexpected content after last section"
             case .sectionSizeMismatch:
                 return "section size mismatch"
             case .illegalOpcode:

Sources/WasmKit/Component/ComponentTypes.swift

@@ -1,6 +1,9 @@
+/// Error type raised from Component Model operations
 public struct ComponentError<Content>: Error {
+    /// The content of the error
     public let content: Content
 
+    /// Initialize a new error with the given content
     public init(_ content: Content) {
         self.content = content
     }

Sources/WasmKit/Docs.docc/Docs.md

@@ -93,8 +93,3 @@ _ = try runtime.invoke(instance, function: "_start")
 - ``CanonicalOptions``
 - ``CanonicalCallContext``
 - ``ComponentError``
-
-### Hook Runtime
-
-- ``RuntimeInterceptor``
-- ``GuestTimeProfiler``

Sources/WasmKit/Execution/Runtime/GuestMemory.swift

@@ -3,6 +3,7 @@ public struct GuestMemory {
     private let store: Store
     private let address: MemoryAddress
 
+    /// Creates a new memory instance from the given store and address
     public init(store: Store, address: MemoryAddress) {
         self.store = store
         self.address = address
@@ -47,24 +48,29 @@ extension GuestPrimitivePointee {
     }
 }
 
+/// Auto implementation of ``GuestPointee`` for ``RawRepresentable`` types
 extension GuestPrimitivePointee where Self: RawRepresentable, Self.RawValue: GuestPointee {
+    /// Reads a value of RawValue type and constructs a value of Self type
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> Self {
         Self(rawValue: .readFromGuest(pointer))!
     }
 
+    /// Writes the raw value of the given value to the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: Self) {
         Self.RawValue.writeToGuest(at: pointer, value: value.rawValue)
     }
 }
 
 extension UInt8: GuestPrimitivePointee {
+    /// Reads a value of `UInt8` type from the given pointer of guest memory
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> UInt8 {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt8.self)
             return pointer.pointee
         }
     }
 
+    /// Writes the given value at the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: UInt8) {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt8.self)
@@ -74,6 +80,7 @@ extension UInt8: GuestPrimitivePointee {
 }
 
 extension UInt16: GuestPrimitivePointee {
+    /// Reads a value of `UInt16` type from the given pointer of guest memory
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> UInt16 {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt16.self)
@@ -86,6 +93,7 @@ extension UInt16: GuestPrimitivePointee {
         }
     }
 
+    /// Writes the given value at the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: UInt16) {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt16.self)
@@ -101,6 +109,7 @@ extension UInt16: GuestPrimitivePointee {
 }
 
 extension UInt32: GuestPrimitivePointee {
+    /// Reads a value of `UInt32` type from the given pointer of guest memory
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> UInt32 {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt32.self)
@@ -113,6 +122,7 @@ extension UInt32: GuestPrimitivePointee {
         }
     }
 
+    /// Writes the given value at the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: UInt32) {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt32.self)
@@ -128,6 +138,7 @@ extension UInt32: GuestPrimitivePointee {
 }
 
 extension UInt64: GuestPrimitivePointee {
+    /// Reads a value of `UInt64` type from the given pointer of guest memory
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> UInt64 {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt64.self)
@@ -140,6 +151,7 @@ extension UInt64: GuestPrimitivePointee {
         }
     }
 
+    /// Writes the given value at the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: UInt64) {
         pointer.withHostPointer { hostPointer in
             let pointer = hostPointer.assumingMemoryBound(to: UInt64.self)
@@ -162,6 +174,7 @@ public struct UnsafeGuestRawPointer {
     /// An offset from the base address of the guest memory region
     public let offset: UInt32
 
+    /// Creates a new pointer from the given memory space and offset
     public init(memorySpace: GuestMemory, offset: UInt32) {
         self.memorySpace = memorySpace
         self.offset = offset
@@ -193,29 +206,39 @@ public struct UnsafeGuestRawPointer {
 }
 
 extension UnsafeGuestRawPointer: GuestPointee {
+    /// Returns the size of this type in bytes in guest memory
     public static var sizeInGuest: UInt32 {
         return UInt32(MemoryLayout<UInt32>.size)
     }
 
+    /// Returns the required alignment of this type, in bytes
     public static var alignInGuest: UInt32 {
         return UInt32(MemoryLayout<UInt32>.alignment)
     }
 
+    /// Reads a value of self type from the given pointer of guest memory
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> UnsafeGuestRawPointer {
         UnsafeGuestRawPointer(memorySpace: pointer.memorySpace, offset: UInt32.readFromGuest(pointer))
     }
 
+    /// Writes the given value at the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: UnsafeGuestRawPointer) {
         UInt32.writeToGuest(at: pointer, value: value.offset)
     }
 }
 
 extension UnsafeGuestRawPointer {
+    /// Returns a boolean value indicating whether the first pointer references a guest
+    /// memory location earlier than the second pointer assuming they point the same guest
+    /// memory space.
     public static func < (lhs: UnsafeGuestRawPointer, rhs: UnsafeGuestRawPointer) -> Bool {
         // Assuming they point the same guest memory space
         lhs.offset < rhs.offset
     }
 
+    /// Returns a boolean value indicating whether the first pointer references a guest
+    /// memory location later than the second pointer assuming they point the same guest
+    /// memory space.
     public static func > (lhs: UnsafeGuestRawPointer, rhs: UnsafeGuestRawPointer) -> Bool {
         // Assuming they point the same guest memory space
         lhs.offset > rhs.offset
@@ -224,12 +247,15 @@ extension UnsafeGuestRawPointer {
 
 /// A pointee-bound pointer representation of guest memory space
 public struct UnsafeGuestPointer<Pointee: GuestPointee> {
+    /// A raw pointer representation of guest memory space
     public let raw: UnsafeGuestRawPointer
 
+    /// Creates a new pointer from the given raw pointer
     public init(_ raw: UnsafeGuestRawPointer) {
         self.raw = raw
     }
 
+    /// Creates a new pointer from the given memory space and offset
     public init(memorySpace: GuestMemory, offset: UInt32) {
         self.raw = UnsafeGuestRawPointer(memorySpace: memorySpace, offset: offset)
     }
@@ -249,47 +275,62 @@ public struct UnsafeGuestPointer<Pointee: GuestPointee> {
 }
 
 extension UnsafeGuestPointer: GuestPointee {
+    /// Returns the size of this type in bytes in guest memory
     public static var sizeInGuest: UInt32 {
         UnsafeGuestRawPointer.sizeInGuest
     }
 
+    /// Returns the required alignment of this type, in bytes
     public static var alignInGuest: UInt32 {
         UnsafeGuestRawPointer.alignInGuest
     }
 
+    /// Reads a value of self type from the given pointer of guest memory
     public static func readFromGuest(_ pointer: UnsafeGuestRawPointer) -> UnsafeGuestPointer<Pointee> {
         UnsafeGuestPointer(UnsafeGuestRawPointer.readFromGuest(pointer))
     }
 
+    /// Writes the given value at the given pointer of guest memory
     public static func writeToGuest(at pointer: UnsafeGuestRawPointer, value: UnsafeGuestPointer<Pointee>) {
         UnsafeGuestRawPointer.writeToGuest(at: pointer, value: value.raw)
     }
 }
 
 extension UnsafeGuestPointer {
+    /// Returns a new pointer offset from this pointer by the specified number of instances.
     public static func + (lhs: UnsafeGuestPointer, rhs: UInt32) -> UnsafeGuestPointer {
         let advanced = lhs.raw.advanced(by: Pointee.sizeInGuest * rhs)
         return UnsafeGuestPointer(advanced)
     }
 
+    /// Returns a new pointer offset from this pointer by the specified number of instances.
     public static func += (lhs: inout Self, rhs: UInt32) {
         lhs = lhs + rhs
     }
 
+    /// Returns a boolean value indicating whether the first pointer references a guest
+    /// memory location earlier than the second pointer assuming they point the same guest
+    /// memory space.
     public static func < (lhs: UnsafeGuestPointer, rhs: UnsafeGuestPointer) -> Bool {
         lhs.raw < rhs.raw
     }
 
+    /// Returns a boolean value indicating whether the first pointer references a guest
+    /// memory location later than the second pointer assuming they point the same guest
+    /// memory space.
     public static func > (lhs: UnsafeGuestPointer, rhs: UnsafeGuestPointer) -> Bool {
         lhs.raw > rhs.raw
     }
 }
 
 /// A pointee-bound interface to a buffer of elements stored contiguously in guest memory
 public struct UnsafeGuestBufferPointer<Pointee: GuestPointee> {
+    /// A pointer to the first element of the buffer
     public let baseAddress: UnsafeGuestPointer<Pointee>
+    /// The number of elements in the buffer
     public let count: UInt32
 
+    /// Creates a new buffer from the given base address and count
     public init(baseAddress: UnsafeGuestPointer<Pointee>, count: UInt32) {
         self.baseAddress = baseAddress
         self.count = count

Sources/WasmKit/Execution/Runtime/Profiler.swift

@@ -3,6 +3,8 @@ import SystemExtras
 import SystemPackage
 
 /// A simple time-profiler for guest process to emit `chrome://tracing` format
+/// This profiler works only when WasmKit is built with debug configuration (`swift build -c debug`)
+@_documentation(visibility: internal)
 public class GuestTimeProfiler: RuntimeInterceptor {
     struct Event: Codable {
         enum Phase: String, Codable {

Sources/WasmKit/Execution/Runtime/Runtime.swift

@@ -11,6 +11,7 @@ public final class Runtime {
     }
 }
 
+@_documentation(visibility: internal)
 public protocol RuntimeInterceptor {
     func onEnterFunction(_ address: FunctionAddress, store: Store)
     func onExitFunction(_ address: FunctionAddress, store: Store)

Sources/WasmKit/Execution/Runtime/Stack.swift

@@ -1,8 +1,7 @@
 /// > Note:
 /// <https://webassembly.github.io/spec/core/exec/runtime.html#stack>
-
-public struct Stack {
-    public enum Element: Equatable {
+struct Stack {
+    enum Element: Equatable {
         case value(Value)
         case label(Label)
         case frame(Frame)
@@ -296,7 +295,7 @@ struct BaseStackAddress {
 
 /// > Note:
 /// <https://webassembly.github.io/spec/core/exec/runtime.html#frames>
-public struct Frame {
+struct Frame {
     let arity: Int
     let module: ModuleAddress
     let baseStackAddress: BaseStackAddress
@@ -323,7 +322,7 @@ public struct Frame {
 }
 
 extension Frame: Equatable {
-    public static func == (_ lhs: Frame, _ rhs: Frame) -> Bool {
+    static func == (_ lhs: Frame, _ rhs: Frame) -> Bool {
         lhs.module == rhs.module && lhs.arity == rhs.arity
     }
 }
@@ -341,7 +340,7 @@ extension Stack {
 }
 
 extension Frame: CustomDebugStringConvertible {
-    public var debugDescription: String {
+    var debugDescription: String {
         "[A=\(arity), BA=\(baseStackAddress), F=\(address?.description ?? "nil")]"
     }
 }

Sources/WasmKit/Execution/Types/Errors.swift

@@ -5,33 +5,40 @@ public enum Trap: Error {
     case unreachable
 
     // Stack
+    /// Stack overflow
     case stackOverflow
-    case stackTypeMismatch(expected: Any.Type, actual: Stack.Element?)
+    /// The stack value type does not match the expected type
     case stackValueTypesMismatch(expected: ValueType, actual: ValueType)
-    case stackElementNotFound(Any.Type, index: Int)
-    case localIndexOutOfRange(index: UInt32)
+    /// Too deep call stack
     case callStackExhausted
 
     // Store
-    case globalAddressOutOfRange(index: GlobalAddress)
-    case globalImmutable(index: GlobalAddress)
+    /// Out of bounds table access
     case outOfBoundsTableAccess(index: ElementIndex)
+    /// Reading a dropped reference
     case readingDroppedReference(index: ElementIndex)
 
     // Invocation
+    /// Exported function not found
     case exportedFunctionNotFound(ModuleInstance, name: String)
+    /// The table element is not initialized
     case tableUninitialized(ElementIndex)
+    /// Undefined element in the table
     case undefinedElement
+    /// Table size overflow
     case tableSizeOverflow
+    /// Indirect call type mismatch
     case callIndirectFunctionTypeMismatch(actual: FunctionType, expected: FunctionType)
+    /// Out of bounds memory access
     case outOfBoundsMemoryAccess
+    /// Invalid function index
     case invalidFunctionIndex(FunctionIndex)
-    case poppedLabelMismatch
-    case labelMismatch
+    /// Integer divided by zero
     case integerDividedByZero
+    /// Integer overflowed during arithmetic operation
     case integerOverflowed
+    /// Invalid conversion to integer
     case invalidConversionToInteger
-    case tooManyBlockParameters([ValueType])
 
     /// Human-readable text representation of the trap that `.wast` text format expects in assertions
     public var assertionText: String {

Sources/WasmKit/Execution/Types/Instances.swift

@@ -146,6 +146,7 @@ public struct MemoryInstance {
     }
 }
 
+/// Instance of a global
 /// > Note:
 /// <https://webassembly.github.io/spec/core/exec/runtime.html#global-instances>
 public struct GlobalInstance {
@@ -160,7 +161,7 @@ public struct GlobalInstance {
 
 /// > Note:
 /// <https://webassembly.github.io/spec/core/exec/runtime.html#element-instances>
-public struct ElementInstance {
+struct ElementInstance {
     public let type: ReferenceType
     public var references: [Reference]
 
@@ -171,9 +172,9 @@ public struct ElementInstance {
 
 /// > Note:
 /// <https://webassembly.github.io/spec/core/exec/runtime.html#syntax-datainst>
-public struct DataInstance {
+struct DataInstance {
     /// Bytes stored in this data instance.
-    public let data: [UInt8]
+    let data: [UInt8]
 }
 
 /// > Note: