Merge pull request #179 from CodaFi/missed-docortunities

Add missing docs

Author: CodaFi

Sources/LLVM/Arbitrary.swift

@@ -12,6 +12,7 @@ import cllvm
 /// supports both the typical integer arithmetic and comparison operations as
 /// well as bitwise manipulation.
 public struct APInt: IRConstant {
+  /// The underlying word size.
   public typealias Word = UInt64
 
   private enum Impl {
@@ -20,6 +21,8 @@ public struct APInt: IRConstant {
   }
 
   private var value: Impl
+
+  /// The bitwidth of this integer.
   public private(set) var bitWidth: Int
 
   fileprivate init(raw values: [Word], _ bits: Int) {
@@ -166,12 +169,16 @@ extension APInt: Numeric {
     self.init(integerLiteral: val)
   }
 
+  /// Returns the result of performing a bitwise AND operation on the two
+  /// given values.
   public static func & (lhs: APInt, rhs: APInt) -> APInt {
     var lhs = lhs
     lhs &= rhs
     return lhs
   }
 
+  /// Stores the result of performing a bitwise AND operation on the two given
+  /// values in the left-hand-side variable.
   public static func &= (lhs: inout APInt, rhs: APInt) {
     precondition(lhs.bitWidth == rhs.bitWidth)
     switch (lhs.value, rhs.value) {
@@ -188,12 +195,16 @@ extension APInt: Numeric {
     }
   }
 
+  /// Returns the result of performing a bitwise OR operation on the two
+  /// given values.
   public static func | (lhs: APInt, rhs: APInt) -> APInt {
     var lhs = lhs
     lhs |= rhs
     return lhs
   }
 
+  /// Stores the result of performing a bitwise OR operation on the two given
+  /// values in the left-hand-side variable.
   public static func |= (lhs: inout APInt, rhs: APInt) {
     precondition(lhs.bitWidth == rhs.bitWidth)
     switch (lhs.value, rhs.value) {
@@ -210,12 +221,16 @@ extension APInt: Numeric {
     }
   }
 
+  /// Returns the result of performing a bitwise XOR operation on the two
+  /// given values.
   public static func ^ (lhs: APInt, rhs: APInt) -> APInt {
     var lhs = lhs
     lhs ^= rhs
     return lhs
   }
 
+  /// Stores the result of performing a bitwise XOR operation on the two given
+  /// values in the left-hand-side variable.
   public static func ^= (lhs: inout APInt, rhs: APInt) {
     precondition(lhs.bitWidth == rhs.bitWidth)
     switch (lhs.value, rhs.value) {
@@ -388,12 +403,16 @@ extension APInt: Numeric {
     }
   }
 
+  /// Returns the result of shifting a value’s binary representation the
+  /// specified number of digits to the left.
   public static func << (lhs: APInt, amount: UInt64) -> APInt {
     var lhs = lhs
     lhs <<= amount
     return lhs
   }
 
+  /// Stores the result of shifting a value’s binary representation the
+  /// specified number of digits to the left in the left-hand-side variable.
   public static func <<= (lhs: inout APInt, amount: UInt64) {
     precondition(amount <= lhs.bitWidth)
     switch lhs.value {

Sources/LLVM/AttachedMetadata.swift

@@ -685,6 +685,7 @@ public class AttachedMetadata {
     self.bounds = bounds
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     guard let ptr = llvm else { return }
     LLVMDisposeValueMetadataEntries(ptr)
@@ -700,6 +701,7 @@ public class AttachedMetadata {
     return Entry(base: self, index: UInt32(index))
   }
 
+  /// Returns the number of metadata entries.
   public var count: Int {
     return self.bounds
   }

Sources/LLVM/DIBuilder.swift

@@ -32,6 +32,7 @@ public final class DIBuilder {
     LLVMDIBuilderFinalize(self.llvm)
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     LLVMDisposeDIBuilder(self.llvm)
   }

Sources/LLVM/IRBuilder.swift

@@ -19,6 +19,7 @@ public class IRBuilder {
     self.llvm = LLVMCreateBuilderInContext(module.context.llvm)
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     LLVMDisposeBuilder(llvm)
   }

Sources/LLVM/IRMetadata.swift

@@ -385,36 +385,67 @@ public struct ExpressionMetadata: IRMetadata {
 
 /// Enumerates the kind of metadata nodes.
 public enum IRMetadataKind {
+  /// The metadata is a string.
   case mdString
+  /// The metadata is a constant-as-metadata node.
   case constantAsMetadata
+  /// The metadata is a local-as-metadata node.
   case localAsMetadata
+  /// The metadata is a disctint metadata operand placeholder.
   case distinctMDOperandPlaceholder
+  /// The metadata is a tuple.
   case mdTuple
+  /// The metadata is a location.
   case location
+  /// The metadata is an expression.
   case expression
+  /// The metadata is a global variable expression.
   case globalVariableExpression
+  /// The metadata is a generic DI node.
   case genericDINode
+  /// The metadata is a subrange.
   case subrange
+  /// The metadata is an enumerator.
   case enumerator
+  /// The metadata is a basic type.
   case basicType
+  /// The metadata is a derived type.
   case derivedType
+  /// The metadata is a composite type.
   case compositeType
+  /// The metadata is a subroutine type.
   case subroutineType
+  /// The metadata is a file.
   case file
+  /// The metadata is a compile unit.
   case compileUnit
+  /// The metadata is a subprogram.
   case subprogram
+  /// The metadata is a lexical block.
   case lexicalBlock
+  /// The metadata is a lexical block file.
   case lexicalBlockFile
+  /// The metadata is a namespace.
   case namespace
+  /// The metadata is a module.
   case module
+  /// The metadata is a template type parameter.
   case templateTypeParameter
+  /// The metadata is a template value parameter.
   case templateValueParameter
+  /// The metadata is a global variable.
   case globalVariable
+  /// The metadata is a local variable.
   case localVariable
+  /// The metadata is a label.
   case label
+  /// The metadata is an Objective-C property.
   case objCProperty
+  /// The metadata is an imported entity.
   case importedEntity
+  /// The metadata is a macro.
   case macro
+  /// The metadata is a macro file.
   case macroFile
 
   fileprivate init(raw: LLVMMetadataKind) {

Sources/LLVM/JIT.swift

@@ -72,6 +72,7 @@ public final class JIT {
     self.init(llvm: LLVMOrcCreateInstance(machine.llvm), ownsContext: true)
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     guard self.ownsContext else {
       return

Sources/LLVM/MemoryBuffer.swift

@@ -115,6 +115,7 @@ public class MemoryBuffer: Sequence {
     return UnsafeBufferPointer(start: start, count: size).makeIterator()
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     guard self.ownsContext else {
       return

Sources/LLVM/Module.swift

@@ -32,10 +32,12 @@ public class Context {
     set { LLVMContextSetDiscardValueNames(self.llvm, newValue.llvm) }
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
-    if ownsContext {
-      LLVMContextDispose(llvm)
+    guard self.ownsContext else {
+      return
     }
+    LLVMContextDispose(self.llvm)
   }
 }
 
@@ -329,6 +331,7 @@ public final class Module: CustomStringConvertible {
     return String(cString: cStr)
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     guard self.ownsContext else {
       return
@@ -587,6 +590,7 @@ extension Module {
       self.bounds = bounds
     }
 
+    /// Deinitialize this value and dispose of its resources.
     deinit {
       guard let ptr = llvm else { return }
       LLVMDisposeModuleFlagsMetadata(ptr)
@@ -602,6 +606,7 @@ extension Module {
       return Entry(base: self, index: UInt32(index))
     }
 
+    /// Returns the number of module flag metadata entries.
     public var count: Int {
       return self.bounds
     }

Sources/LLVM/ObjectFile.swift

@@ -37,6 +37,7 @@ public class ObjectFile {
     return SymbolSequence(llvm: LLVMGetSymbols(llvm), object: self)
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     LLVMDisposeObjectFile(llvm)
   }
@@ -100,6 +101,7 @@ public class SectionSequence: Sequence {
     }
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     LLVMDisposeSectionIterator(llvm)
   }
@@ -171,6 +173,7 @@ public class RelocationSequence: Sequence {
     }
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     LLVMDisposeSectionIterator(llvm)
   }
@@ -198,6 +201,7 @@ public class SymbolSequence: Sequence {
     }
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     LLVMDisposeSymbolIterator(llvm)
   }

Sources/LLVM/TargetMachine.swift

@@ -273,6 +273,7 @@ public class TargetMachine {
     return MemoryBuffer(llvm: llvm)
   }
 
+  /// Deinitialize this value and dispose of its resources.
   deinit {
     guard self.ownsContext else {
       return