Merge pull request #91 from swift-developer-tools/ops/readme-and-cleanup

Update memory-safety overview

Author: swift-developer-tools-archive

README.md

@@ -14,17 +14,19 @@ initialization macros. Direct access to the libgit2 C library is also provided
 by the package. See [Usage](#Usage) for an example of how to import and use 
 either library.
 
+The bindings use memory-safe Swift types wherever possible, while preserving 
+libgit2's behavior and semantics. For example, some bindings use native Swift 
+types like `String` instead of `UnsafePointer<CChar>`, and accept `inout` 
+parameters to memory-safe Swift structs instead of unsafe pointers to C structs. 
+In these cases, swift-libgit2 safely converts types between Swift and C, 
+managing and freeing memory as needed. See 
+[Memory Management](#Memory-Management) for more information.
+
 The bindings use the same signatures and names as their C equivalents, but are 
 written using [camel case](https://en.wikipedia.org/wiki/Camel_case) instead of 
-[snake case](https://en.wikipedia.org/wiki/Snake_case).
-
-Similar to libgit2, the bindings do not use 
-[namespaces](https://en.wikipedia.org/wiki/Namespace). All bindings are 
-available globally.
-
-The bindings use native Swift types wherever possible, while preserving 
-libgit2's behavior and semantics. For example, some bindings use Swift types 
-like `String` instead of `UnsafePointer<CChar>`.
+[snake case](https://en.wikipedia.org/wiki/Snake_case). Similar to libgit2, the 
+bindings do not use [namespaces](https://en.wikipedia.org/wiki/Namespace). All 
+bindings are available globally.
 
 
 
@@ -103,13 +105,17 @@ converted from Swift to C, or in other cases specific to individual functions.
 
 ### Memory Management
 
-swift-libgit2 directly invokes libgit2 C code. The caller is responsible for 
-freeing memory allocated by libgit2, unless otherwise specified.
+swift-libgit2 handles memory management for most bindings. For example, `inout` 
+Swift types are safely converted between Swift and C, with any allocated 
+memory being freed as needed.
+
+However, some bindings require manual memory management, particularly when 
+working with opaque or unsafe pointers. The caller is responsible for freeing 
+the memory using the appropriate swift-libgit2 or libgit2 function.
 
 Consider using 
 [`defer`](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/statements/#Defer-Statement)
-statements with memory-freeing function bindings to consistently and safely 
-free memory.
+statements with memory-freeing functions to consistently and safely free memory.
 
 ### Thread Safety
 

Sources/SwiftLibgit2/Diff-Advanced/Diff-Advanced-Structs.swift

@@ -35,7 +35,7 @@ public struct GitDiffPerfData: CStructInternalMutable, CConvertible, Sendable
 
 
 
-    /// Initializes a default ``GitDiffPerfData``.
+    /// Initializes a default ``GitDiffPerfData`` instance.
     public init() { }
 
 

Sources/SwiftLibgit2/Diff/Diff-Functions.swift

@@ -784,13 +784,13 @@ public func gitDiffBlobToBuffer(
 
             return try buffer.withOptionalCString
             {
-                cBuffer, cBufferLength in
+                cBuffer, cBufferCount in
 
                 return git_diff_blob_to_buffer(
                     oldBlob,
                     oldAsPath,
                     cBuffer,
-                    cBufferLength,
+                    cBufferCount,
                     bufferAsPath,
                     cOptions,
                     fileCB,

Sources/SwiftLibgit2/Diff/Diff-Structs.swift

@@ -635,7 +635,7 @@ public struct GitDiffHunk: CStructInternalMutable, CConvertible, Sendable
 
 
 
-    /// Initializes a default ``GitDiffHunk``.
+    /// Initializes a default ``GitDiffHunk`` instance.
     public init() { }
 
 

Sources/SwiftLibgit2/SwiftLibgit2.docc/SwiftLibgit2.md

@@ -18,17 +18,19 @@ initialization macros. Direct access to the libgit2 C library is also provided
 by the package. See [Usage](#Usage) for an example of how to import and use 
 either library.
 
+The bindings use memory-safe Swift types wherever possible, while preserving 
+libgit2's behavior and semantics. For example, some bindings use native Swift 
+types like `String` instead of `UnsafePointer<CChar>`, and accept `inout` 
+parameters to memory-safe Swift structs instead of unsafe pointers to C structs. 
+In these cases, swift-libgit2 safely converts types between Swift and C, 
+managing and freeing memory as needed. See 
+[Memory Management](#Memory-Management) for more information.
+
 The bindings use the same signatures and names as their C equivalents, but are 
 written using [camel case](https://en.wikipedia.org/wiki/Camel_case) instead of 
-[snake case](https://en.wikipedia.org/wiki/Snake_case).
-
-Similar to libgit2, the bindings do not use 
-[namespaces](https://en.wikipedia.org/wiki/Namespace). All bindings are 
-available globally.
-
-The bindings use native Swift types wherever possible, while preserving 
-libgit2's behavior and semantics. For example, some bindings use Swift types 
-like `String` instead of `UnsafePointer<CChar>`.
+[snake case](https://en.wikipedia.org/wiki/Snake_case). Similar to libgit2, the 
+bindings do not use [namespaces](https://en.wikipedia.org/wiki/Namespace). All 
+bindings are available globally.
 
 
 
@@ -107,13 +109,17 @@ converted from Swift to C, or in other cases specific to individual functions.
 
 ### Memory Management
 
-swift-libgit2 directly invokes libgit2 C code. The caller is responsible for 
-freeing memory allocated by libgit2, unless otherwise specified.
+swift-libgit2 handles memory management for most bindings. For example, `inout` 
+Swift types are safely converted between Swift and C, with any allocated 
+memory being freed as needed.
+
+However, some bindings require manual memory management, particularly when 
+working with opaque or unsafe pointers. The caller is responsible for freeing 
+the memory using the appropriate swift-libgit2 or libgit2 function.
 
 Consider using 
 [`defer`](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/statements/#Defer-Statement)
-statements with memory-freeing function bindings to consistently and safely 
-free memory.
+statements with memory-freeing functions to consistently and safely free memory.
 
 ### Thread Safety
 

Sources/SwiftLibgit2/Utilities/Extensions/NSError+MakeError.swift

@@ -34,7 +34,7 @@ internal extension NSError
         return NSError(
             domain:     Bundle.main.bundleIdentifier ?? "swift-libgit2",
             code:       Int(code),
-            userInfo:   [NSLocalizedDescriptionKey: message]
+            userInfo:   [NSLocalizedDescriptionKey : message]
         )
     }
 

Sources/SwiftLibgit2/Utilities/Protocols/CFreeable.swift

@@ -12,7 +12,7 @@
 ///
 /// A struct that conforms to ``CStructInternalMutable`` may also need to
 /// conform to ``CFreeable`` if libgit2 provides a corresponding memory-freeing
-/// function. See the ``CStruct`` documenation for more information.
+/// function. See the ``CStruct`` documentation for more information.
 internal protocol CFreeable: CStruct
 {
     /// The type of the pointer passed to ``freeCValue(_:)`` to free the memory

Tests/SwiftLibgit2Tests/Commit-Tests.swift

@@ -326,7 +326,7 @@ final class CommitTests: XCTestCaseStopOnFail
 
             XCTAssertGreaterThan(callbackData.callCount, 0)
             XCTAssertNotNil(callbackData.lastMessage)
-            XCTAssertFalse(callbackData.lastMessage?.isEmpty ?? false)
+            XCTAssertFalse(callbackData.lastMessage?.isEmpty ?? true)
         }
     }
 

Tests/SwiftLibgit2Tests/Diff-Tests.swift

@@ -172,7 +172,7 @@ final class DiffTests: XCTestCaseStopOnFail
             _ = gitDiffBlobs(
                 oldBlob:    oldBlobPointer,
                 oldAsPath:  "old.txt",
-                newBlob:     newBlobPointer,
+                newBlob:    newBlobPointer,
                 newAsPath:  "new.txt",
                 options:    nil,
                 fileCB:     nil,

Tests/Utilities/Repository.swift

@@ -1038,7 +1038,7 @@ internal extension Repository
         _ body: (Repository, OpaquePointer) throws -> T
     ) throws -> T
     {
-        return try Repository.withRepository
+        return try withRepository
         {
             repository in
 
@@ -1128,7 +1128,7 @@ internal extension Repository
         _ body: (Repository, OpaquePointer) throws -> T
     ) throws -> T
     {
-        return try Repository.withRepository
+        return try withRepository
         {
             repository in
 
@@ -1180,7 +1180,7 @@ internal extension Repository
         _ body: (Repository, OpaquePointer) throws -> T
     ) throws -> T
     {
-        return try Repository.withRepository
+        return try withRepository
         {
             repository in
 
@@ -1239,7 +1239,7 @@ internal extension Repository
         _ body  : (Repository, OpaquePointer) throws -> T
     ) throws -> T
     {
-        return try Repository.withRepository
+        return try withRepository
         {
             repository in
 
@@ -1272,7 +1272,7 @@ internal extension Repository
                         repo:   repository.pointer,
                         name:   Self.remoteName,
                         url:    Self.remoteURL,
-                        fetch:  Repository.fetchRefspec
+                        fetch:  fetchRefspec
                     )
             }
 
@@ -1368,7 +1368,7 @@ internal extension Repository
         _ body: (Repository, OpaquePointer) throws -> T
     ) throws -> T
     {
-        return try Repository.withRepository
+        return try withRepository
         {
             repository in
 
@@ -1426,7 +1426,7 @@ internal extension Repository
         _ body  : (Repository, OpaquePointer) throws -> T
     ) throws -> T
     {
-        return try Repository.withRepository
+        return try withRepository
         {
             repository in