Merge pull request #163 from CodaFi/documentary-crew

Restore Documentation to 100%

Author: CodaFi

Sources/LLVM/JIT.swift

@@ -5,6 +5,10 @@ import cllvm
 /// JITError represents the different kinds of errors the JIT compiler can
 /// throw.
 public enum JITError: Error, CustomStringConvertible {
+  /// A generic error thrown by the JIT during exceptional circumstances.
+  ///
+  /// In general, it is not safe to catch and continue after this exception has
+  /// been thrown.
   case generic(String)
 
   public var description: String {
@@ -23,7 +27,31 @@ public enum JITError: Error, CustomStringConvertible {
 /// The JIT is fundamentally lazy, and allows control over when and how symbols
 /// are resolved.
 public final class JIT {
-  public typealias TargetAddress = LLVMOrcTargetAddress
+  /// A type that represents an address, either symbolically within the JIT or
+  /// physically in the execution environment.
+  public struct TargetAddress: Comparable {
+    fileprivate var llvm: LLVMOrcTargetAddress
+
+    /// Creates a target address value of `0`.
+    public init() {
+      self.llvm = 0
+    }
+
+    /// Creates a target address from a raw address value.
+    public init(raw: LLVMOrcTargetAddress) {
+      self.llvm = raw
+    }
+
+    public static func == (lhs: TargetAddress, rhs: TargetAddress) -> Bool {
+      return lhs.llvm == rhs.llvm
+    }
+
+    public static func < (lhs: TargetAddress, rhs: TargetAddress) -> Bool {
+      return lhs.llvm < rhs.llvm
+    }
+  }
+
+  /// Represents a handle to a module owned by the JIT stack.
   public struct ModuleHandle {
     fileprivate var llvm: LLVMOrcModuleHandle
   }
@@ -77,13 +105,13 @@ public final class JIT {
   ///   restrict the search, if any.
   /// - returns: The address of the symbol, or 0 if it does not exist.
   public func address(of symbol: String, in module: ModuleHandle? = nil) throws -> TargetAddress {
-    var retAddr: TargetAddress = 0
+    var retAddr: LLVMOrcTargetAddress = 0
     if let targetModule = module {
       try checkForJITError(LLVMOrcGetSymbolAddressIn(self.llvm, &retAddr, targetModule.llvm, symbol))
     } else {
       try checkForJITError(LLVMOrcGetSymbolAddress(self.llvm, &retAddr, symbol))
     }
-    return retAddr
+    return TargetAddress(raw: retAddr)
   }
 
   // MARK: Lazy Compilation
@@ -103,11 +131,11 @@ public final class JIT {
   /// - returns: The target address representing a stub.  Calling this stub
   ///   forces the given compilation callback to fire.
   public func registerLazyCompile(_ callback: @escaping (JIT) -> TargetAddress) throws -> TargetAddress {
-    var addr: TargetAddress = 0
+    var addr: LLVMOrcTargetAddress = 0
     let callbackContext = ORCLazyCompileCallbackContext(callback)
     let contextPtr = Unmanaged<ORCLazyCompileCallbackContext>.passRetained(callbackContext).toOpaque()
     try checkForJITError(LLVMOrcCreateLazyCompileCallback(self.llvm, &addr, lazyCompileBlockTrampoline, contextPtr))
-    return addr
+    return TargetAddress(raw: addr)
   }
 
   // MARK: Stubs
@@ -120,7 +148,7 @@ public final class JIT {
   /// - parameter name: The name of the indirect stub.
   /// - parameter address: The address of the indirect stub.
   public func createIndirectStub(named name: String, address: TargetAddress) throws {
-    try checkForJITError(LLVMOrcCreateIndirectStub(self.llvm, name, address))
+    try checkForJITError(LLVMOrcCreateIndirectStub(self.llvm, name, address.llvm))
   }
 
   /// Resets the address of an indirect stub.
@@ -132,7 +160,7 @@ public final class JIT {
   /// - parameter name: The name of an indirect stub.
   /// - parameter address: The address to set the indirect stub to point to.
   public func setIndirectStubPointer(named name: String, address: TargetAddress) throws {
-    try checkForJITError(LLVMOrcSetIndirectStubPointer(self.llvm, name, address))
+    try checkForJITError(LLVMOrcSetIndirectStubPointer(self.llvm, name, address.llvm))
   }
 
   // MARK: Adding Code to the JIT
@@ -251,7 +279,7 @@ private let lazyCompileBlockTrampoline : LLVMOrcLazyCompileCallbackFn = { (callb
 
   let tempJIT = JIT(llvm: jit, ownsContext: false)
   let callback = Unmanaged<ORCLazyCompileCallbackContext>.fromOpaque(ctx).takeUnretainedValue()
-  return callback.block(tempJIT)
+  return callback.block(tempJIT).llvm
 }
 
 private let symbolBlockTrampoline : LLVMOrcSymbolResolverFn = { (callbackName, callbackCtx) in
@@ -261,7 +289,7 @@ private let symbolBlockTrampoline : LLVMOrcSymbolResolverFn = { (callbackName, c
 
   let name = String(cString: cname)
   let callback = Unmanaged<ORCSymbolCallbackContext>.fromOpaque(ctx).takeUnretainedValue()
-  return callback.block(name)
+  return callback.block(name).llvm
 }
 
 private class ORCLazyCompileCallbackContext {

Sources/LLVM/Metadata.swift

@@ -2,7 +2,11 @@
 import cllvm
 #endif
 
+/// An unfortunate artifact of the design of the metadata class hierarchy is
+/// that you may find it convenient to force-cast metadata nodes.  In general,
+/// this behavior is not encouraged, but it will be supported for now.
 public protocol _IRMetadataInitializerHack {
+  /// Initialize a metadata node from a raw LLVM metadata ref.
   init(llvm: LLVMMetadataRef)
 }
 
@@ -38,6 +42,7 @@ public protocol _IRMetadataInitializerHack {
 ///   formats. This allows compatibility with traditional machine-code level
 ///   debuggers, like GDB, DBX, or CodeView.
 public protocol Metadata: _IRMetadataInitializerHack {
+  /// Retrieves the underlying LLVM metadata object.
   func asMetadata() -> LLVMMetadataRef
 }
 
@@ -56,6 +61,11 @@ extension Metadata {
     LLVMDumpValue(LLVMMetadataAsValue(LLVMGetGlobalContext(), self.asMetadata()))
   }
 
+  /// Force-casts metadata to a destination type.
+  ///
+  /// - warning: In general, use of this method is discouraged and can
+  ///   lead to unpredictable results or undefined behavior.  No checks are
+  ///   performed before, during, or after the cast.
   public func forceCast<DestTy: Metadata>(to: DestTy.Type) -> DestTy {
     return DestTy(llvm: self.asMetadata())
   }
@@ -300,6 +310,8 @@ public struct ImportedEntityMetadata: DIType {
   }
 }
 
+/// `NameSpaceMetadata` nodes represent subroutines in the source program.
+/// They are attached to corresponding LLVM IR functions.
 public struct FunctionMetadata: DIScope {
   internal let llvm: LLVMMetadataRef
 
@@ -312,6 +324,7 @@ public struct FunctionMetadata: DIScope {
   }
 }
 
+/// `NameSpaceMetadata` nodes represent entities like C++ modules.
 public struct ModuleMetadata: DIScope {
   internal let llvm: LLVMMetadataRef
 
@@ -324,6 +337,7 @@ public struct ModuleMetadata: DIScope {
   }
 }
 
+/// `NameSpaceMetadata` nodes represent entities like C++ namespaces.
 public struct NameSpaceMetadata: DIScope {
   internal let llvm: LLVMMetadataRef
 

Sources/LLVM/MetadataAttributes.swift

@@ -435,6 +435,9 @@ public enum DIAttributeTypeEncoding {
   }
 }
 
+/// Enumerates a set of flags that can be applied to metadata nodes to change
+/// their interpretation at compile time or attach additional semantic
+/// significance at runtime.
 public struct DIFlags : OptionSet {
   public let rawValue: LLVMDIFlags.RawValue
 

Sources/LLVM/NamedMetadata.swift

@@ -6,7 +6,9 @@ import cllvm
 /// by a user-provided name.  Named metadata is generated lazily when operands
 /// are attached.
 public class NamedMetadata {
+  /// The module with which this named metadata is associated.
   public let module: Module
+  /// The name associated with this named metadata.
   public let name: String
 
   init(module: Module, name: String) {

Sources/LLVM/Units.swift

@@ -140,6 +140,9 @@ public struct Size {
     return Size(value & ~mask)
   }
 
+  /// Returns the remainder of dividing the first size value
+  /// by the second alignment value.  This has the effect of aligning the
+  /// size value subtractively.
   public static func % (lhs: Size, rhs: Alignment) -> Size {
     return Size(lhs.rawValue % UInt64(rhs.rawValue))
   }
@@ -232,20 +235,6 @@ extension Size: UnsignedInteger {
     lhs = Size(lhs.rawValue * rhs.rawValue)
   }
 
-  public static func * (lhs: Size, rhs: UInt64) -> Size {
-    var lhs = lhs
-    lhs *= Size(rhs)
-    return lhs
-  }
-  public static func * (lhs: UInt64, rhs: Size) -> Size {
-    var lhs = Size(lhs)
-    lhs *= rhs
-    return lhs
-  }
-  public static func *= (lhs: inout Size, rhs: UInt64) {
-    lhs = Size(lhs.rawValue * rhs)
-  }
-
   public static func / (lhs: Size, rhs: Size) -> Size {
     var lhs = lhs
     lhs /= rhs
@@ -296,3 +285,25 @@ extension Size: UnsignedInteger {
   public typealias IntegerLiteralType = UInt64
   public typealias Words = UInt64.Words
 }
+
+extension Size {
+  /// Multiplies a size value by a raw unitless value and produces their product.
+  public static func * (lhs: Size, rhs: UInt64) -> Size {
+    var lhs = lhs
+    lhs *= Size(rhs)
+    return lhs
+  }
+
+  /// Multiplies a raw unitless value by a size value and produces their product.
+  public static func * (lhs: UInt64, rhs: Size) -> Size {
+    var lhs = Size(lhs)
+    lhs *= rhs
+    return lhs
+  }
+
+  /// Multiplies a size value by a raw unitless value and stores the result in
+  /// the left-hand-side size variable.
+  public static func *= (lhs: inout Size, rhs: UInt64) {
+    lhs = Size(lhs.rawValue * rhs)
+  }
+}

Tests/LLVMTests/JITSpec.swift

@@ -104,7 +104,7 @@ class JITSpec : XCTestCase {
         _ = try jit.addEagerlyCompiledIR(module) { (name) -> JIT.TargetAddress in
           gotForced = true
           guard name == testFuncName else {
-            return 0
+            return JIT.TargetAddress()
           }
           return getUnderlyingCDecl(calculateFibs)
         }
@@ -134,7 +134,7 @@ class JITSpec : XCTestCase {
         _ = try jit.addLazilyCompiledIR(module) { (name) -> JIT.TargetAddress in
           gotForced = true
           guard name == testFuncName else {
-            return 0
+            return JIT.TargetAddress()
           }
           return getUnderlyingCDecl(calculateFibs)
         }
@@ -169,12 +169,12 @@ class JITSpec : XCTestCase {
       let testFuncName = jit.mangle(symbol: "calculateSwiftFibs")
       _ = try jit.addObjectFile(objBuffer) { (name) -> JIT.TargetAddress in
         guard name == testFuncName else {
-          return 0
+          return JIT.TargetAddress()
         }
         return getUnderlyingCDecl(calculateFibs)
       }
       let mainAddr = try jit.address(of: "main")
-      XCTAssert(mainAddr != 0)
+      XCTAssert(mainAddr != JIT.TargetAddress())
     } catch _ {
       XCTFail()
     }
@@ -190,7 +190,7 @@ class JITSpec : XCTestCase {
           let sm = self.buildTestModule()
           _ = try! jit.addEagerlyCompiledIR(sm) { (name) -> JIT.TargetAddress in
             guard name == testFuncName else {
-              return 0
+              return JIT.TargetAddress()
             }
             return getUnderlyingCDecl(calculateFibs)
           }
@@ -223,7 +223,7 @@ class JITSpec : XCTestCase {
           let sm = self.buildTestModule()
           _ = try! jit.addEagerlyCompiledIR(sm) { (name) -> JIT.TargetAddress in
             guard name == testFuncName else {
-              return 0
+              return JIT.TargetAddress()
             }
             return getUnderlyingCDecl(calculateFibs)
           }