Merge pull request #74 from p-x9/docc/dyld-cache

Add doc comment about `DyldCache`
p-x9 · Apr 11, 2024 · fb2071f · fb2071f
2 parents 847fcfd + 4a949e3
commit fb2071f
Show file tree

Hide file tree

Showing 9 changed files with 71 additions and 1 deletion.
diff --git a/Sources/MachOKit/DyldCache.swift b/Sources/MachOKit/DyldCache.swift
@@ -9,14 +9,20 @@
 import Foundation
 
 public class DyldCache {
+    /// URL of loaded dyld cache file
     public let url: URL
     let fileHandle: FileHandle
 
     public var headerSize: Int {
         DyldCacheHeader.layoutSize
     }
 
+    /// Header for dyld cache
     public let header: DyldCacheHeader
+
+    /// Target CPU info.
+    ///
+    /// It is obtained based on magic.
     public let cpu: CPU
 
     public init(url: URL) throws {
@@ -46,6 +52,7 @@ public class DyldCache {
 }
 
 extension DyldCache {
+    /// Sequence of mapping infos
     public var mappingInfos: DataSequence<DyldCacheMappingInfo>? {
         guard header.mappingCount > 0 else { return nil }
         return fileHandle.readDataSequence(
@@ -54,6 +61,7 @@ extension DyldCache {
         )
     }
 
+    /// Sequence of mapping and slide infos
     public var mappingAndSlideInfos: DataSequence<DyldCacheMappingAndSlideInfo>? {
         guard header.mappingWithSlideCount > 0 else { return nil }
         return fileHandle.readDataSequence(
@@ -62,6 +70,7 @@ extension DyldCache {
         )
     }
 
+    /// Sequence of image infos.
     public var imageInfos: DataSequence<DyldCacheImageInfo>? {
         guard header.imagesCount > 0 else { return nil }
         return fileHandle.readDataSequence(
@@ -70,6 +79,7 @@ extension DyldCache {
         )
     }
 
+    /// Sequence of image text infos.
     public var imageTextInfos: DataSequence<DyldCacheImageTextInfo>? {
         guard header.imagesTextCount > 0 else { return nil }
         return fileHandle.readDataSequence(
@@ -78,7 +88,9 @@ extension DyldCache {
         )
     }
 
-    /// check if entry type is `dyld_subcache_entry_v1` or `dyld_subcache_entry`
+    /// Sub cache type
+    ///
+    /// Check if entry type is `dyld_subcache_entry_v1` or `dyld_subcache_entry`
     public var subCacheEntryType: DyldSubCacheEntryType? {
         guard header.subCacheArrayCount > 0 else {
             return nil
@@ -95,13 +107,15 @@ extension DyldCache {
         }
     }
 
+    /// Local symbol info
     public var localSymbolsInfo: DyldCacheLocalSymbolsInfo? {
         guard header.localSymbolsSize > 0 else { return nil }
         return fileHandle.read(
             offset: header.localSymbolsOffset
         )
     }
 
+    /// Sequence of sub caches
     public var subCaches: SubCaches? {
         guard let subCacheEntryType else { return nil }
         fileHandle.seek(toFileOffset: numericCast(header.subCacheArrayOffset))
@@ -117,6 +131,7 @@ extension DyldCache {
 }
 
 extension DyldCache {
+    /// Sequence of MachO information contained in this cache
     public func machOFiles() -> AnySequence<MachOFile> {
         guard let imageInfos = imageInfos else {
             return AnySequence([])

diff --git a/Sources/MachOKit/Header/DyldCacheHeader/DyldCacheHeader.swift b/Sources/MachOKit/Header/DyldCacheHeader/DyldCacheHeader.swift
@@ -15,43 +15,53 @@ public struct DyldCacheHeader: LayoutWrapper {
 }
 
 extension DyldCacheHeader {
+    /// dyld_cache magic number identifier
     public var magic: String {
         .init(tuple: layout.magic)
     }
 
+    /// Unique value for each shared cache file
     public var uuid: UUID {
         .init(uuid: layout.uuid)
     }
 
+    /// Type of dyld  cache.
     public var cacheType: DyldCacheType {
         .init(rawValue: layout.cacheType)!
     }
 
+    /// Sub type of dyld cache for a multi-cache, nil otherwise.
     public var cacheSubType: DyldCacheSubType? {
         guard cacheType == .multiCache else { return nil }
         return .init(rawValue: layout.cacheSubType)
     }
 
+    /// Target Platform
     public var platform: Platform {
         .init(rawValue: layout.platform) ?? .unknown
     }
 
+    /// A boolean value that indicates whether this cache targets simulator
     public var isSimulator: Bool {
         layout.simulator != 0
     }
 
+    /// Target OS version
     public var osVersion: Version {
         .init(layout.osVersion)
     }
 
+    /// Alternative target platform.
     public var altPlatform: Platform {
         .init(rawValue: layout.altPlatform) ?? .unknown
     }
 
+    /// Alternative target OS version
     public var altOsVersion: Version {
         .init(layout.altOsVersion)
     }
 
+    /// UUID of the associated symbol file.
     public var symbolFileUUID: UUID {
         .init(uuid: layout.symbolFileUUID)
     }

diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheImageInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheImageInfo.swift
@@ -15,6 +15,9 @@ public struct DyldCacheImageInfo: LayoutWrapper {
 }
 
 extension DyldCacheImageInfo {
+    /// Path for image
+    /// - Parameter cache: DyldCache to which this image belongs
+    /// - Returns: Path for image
     public func path(in cache: DyldCache) -> String? {
         cache.fileHandle.readString(
             offset: numericCast(layout.pathFileOffset),

diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheImageTextInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheImageTextInfo.swift
@@ -15,10 +15,14 @@ public struct DyldCacheImageTextInfo: LayoutWrapper {
 }
 
 extension DyldCacheImageTextInfo {
+    /// UUID of this image text
     public var uuid: UUID {
         .init(uuid: layout.uuid)
     }
 
+    /// Path for image text
+    /// - Parameter cache: DyldCache to which this image belongs
+    /// - Returns: Path for image text
     public func path(in cache: DyldCache) -> String? {
         cache.fileHandle.readString(
             offset: numericCast(layout.pathOffset),

diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheLocalSymbolsInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheLocalSymbolsInfo.swift
@@ -15,6 +15,9 @@ public struct DyldCacheLocalSymbolsInfo: LayoutWrapper {
 }
 
 extension DyldCacheLocalSymbolsInfo {
+    /// Sequence of 64-bit architecture symbols
+    /// - Parameter cache: DyldCache to which `self` belongs
+    /// - Returns: Sequence of symbols
     public func symbols64(in cache: DyldCache) -> MachOFile.Symbols64? {
         guard cache.cpu.is64Bit else { return nil }
 
@@ -36,6 +39,9 @@ extension DyldCacheLocalSymbolsInfo {
         )
     }
 
+    /// Sequence of 32-bit architecture symbols
+    /// - Parameter cache: DyldCache to which `self` belongs
+    /// - Returns: Sequence of symbols
     public func symbols32(in cache: DyldCache) -> MachOFile.Symbols? {
         guard !cache.cpu.is64Bit else { return nil }
 
@@ -57,6 +63,9 @@ extension DyldCacheLocalSymbolsInfo {
         )
     }
 
+    /// Sequence of symbols
+    /// - Parameter cache: DyldCache to which `self` belongs
+    /// - Returns: Sequence of symbols
     public func symbols(in cache: DyldCache) -> AnyRandomAccessCollection<MachOFile.Symbol> {
         if let symbols64 = symbols64(in: cache) {
             return AnyRandomAccessCollection(symbols64)
@@ -69,6 +78,9 @@ extension DyldCacheLocalSymbolsInfo {
 }
 
 extension DyldCacheLocalSymbolsInfo {
+    /// Sequence of 64-bit architecture symbols entries
+    /// - Parameter cache: DyldCache to which `self` belongs
+    /// - Returns: Sequence of  symbols entries
     public func entries64(
         in cache: DyldCache
     ) -> DataSequence<DyldCacheLocalSymbolsEntry64>? {
@@ -81,6 +93,9 @@ extension DyldCacheLocalSymbolsInfo {
         )
     }
 
+    /// Sequence of 32-bit architecture symbols entries
+    /// - Parameter cache: DyldCache to which `self` belongs
+    /// - Returns: Sequence of  symbols entries
     public func entries32(
         in cache: DyldCache
     ) -> DataSequence<DyldCacheLocalSymbolsEntry>? {
@@ -94,6 +109,9 @@ extension DyldCacheLocalSymbolsInfo {
         )
     }
 
+    /// Sequence of symbols entries
+    /// - Parameter cache: DyldCache to which `self` belongs
+    /// - Returns: Sequence of  symbols entries
     public func entries(
         in cache: DyldCache
     ) -> AnyRandomAccessCollection<DyldCacheLocalSymbolsEntryProtocol> {

diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheMappingAndSlideInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheMappingAndSlideInfo.swift
@@ -15,14 +15,17 @@ public struct DyldCacheMappingAndSlideInfo: LayoutWrapper {
 }
 
 extension DyldCacheMappingAndSlideInfo {
+    /// Flags of mapping
     public var flags: DyldCacheMappingFlags {
         .init(rawValue: layout.flags)
     }
 
+    /// Max vm protection of this mapping
     public var maxProtection: VMProtection {
         .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt))
     }
 
+    /// Initial vm protection of this mapping
     public var initialProtection: VMProtection {
         .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt))
     }

diff --git a/Sources/MachOKit/Model/DyldCache/DyldCacheMappingInfo.swift b/Sources/MachOKit/Model/DyldCache/DyldCacheMappingInfo.swift
@@ -15,10 +15,12 @@ public struct DyldCacheMappingInfo: LayoutWrapper {
 }
 
 extension DyldCacheMappingInfo {
+    /// Max vm protection of this mapping
     public var maxProtection: VMProtection {
         .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt))
     }
 
+    /// Initial vm protection of this mapping
     public var initialProtection: VMProtection {
         .init(rawValue: VMProtection.RawValue(bitPattern: layout.maxProt))
     }

diff --git a/Sources/MachOKit/Model/DyldCache/DyldSubCacheEntry.swift b/Sources/MachOKit/Model/DyldCache/DyldSubCacheEntry.swift
@@ -33,20 +33,25 @@ public enum DyldSubCacheEntry {
         }
     }
 
+    /// UUID of sub cache
     public var uuid: UUID {
         switch self {
         case let .general(info): info.uuid
         case let .v1(info): info.uuid
         }
     }
 
+    /// Offset of this subcache from the main cache base address
     public var cacheVMOffset: UInt64 {
         switch self {
         case let .general(info): info.cacheVMOffset
         case let .v1(info): info.cacheVMOffset
         }
     }
 
+    /// File name suffix of the subCache file
+    ///
+    /// e.g. ".25.data", ".03.development"
     public var fileSuffix: String? {
         switch self {
         case let .general(info): info.fileSuffix
@@ -62,6 +67,7 @@ public struct DyldSubCacheEntryV1: LayoutWrapper {
 }
 
 extension DyldSubCacheEntryV1 {
+    /// UUID of sub cache
     public var uuid: UUID {
         .init(uuid: layout.uuid)
     }
@@ -74,10 +80,14 @@ public struct DyldSubCacheEntryGeneral: LayoutWrapper {
 }
 
 extension DyldSubCacheEntryGeneral {
+    /// UUID of sub cache
     public var uuid: UUID {
         .init(uuid: layout.uuid)
     }
 
+    /// File name suffix of the subCache file
+    ///
+    /// e.g. ".25.data", ".03.development"
     public var fileSuffix: String {
         .init(tuple: layout.fileSuffix)
     }

diff --git a/Sources/MachOKit/Protocol/DyldCacheLocalSymbolsEntryProtocol.swift b/Sources/MachOKit/Protocol/DyldCacheLocalSymbolsEntryProtocol.swift
@@ -9,7 +9,12 @@
 import Foundation
 
 public protocol DyldCacheLocalSymbolsEntryProtocol {
+    /// Offset in cache file of start of dylib
     var dylibOffset: Int { get }
+
+    /// Start index of locals for this dylib
     var nlistStartIndex: Int { get }
+
+    /// Number of local symbols for this dylib
     var nlistCount: Int { get }
 }