Add docs for PackageReader and PackageWriter

Author: tomasf

Sources/ThreeMF/Package/PackageReader.swift

@@ -2,6 +2,17 @@ import Foundation
 import Zip
 import Nodal
 
+/// Reads 3MF packages from either a file URL or in‑memory data and provides access to parsed models and file contents.
+///
+/// PackageReader abstracts the underlying ZIP archive and exposes high‑level methods to:
+/// - Load the root model or a model at a specific path inside the package
+/// - Read raw file data from a given URL within the package
+///
+/// Usage:
+/// - Initialize with a URL or Data
+/// - Call `model()` to load the root model, or `model(at:)` to load a specific model file
+/// - Use `readFile(at:)` to access arbitrary file contents inside the package
+/// 
 public struct PackageReader<Target> {
     private let archive: ZipArchive<Target>
 
@@ -11,16 +22,27 @@ public struct PackageReader<Target> {
 }
 
 public extension PackageReader<URL> {
+    /// Creates a reader that opens a 3MF package from a file URL.
+    ///
+    /// - Parameter fileURL: The URL of the 3MF package to open.
+    /// - Throws: An error if the archive cannot be opened.
     init(url fileURL: URL) throws {
         try self.init(archive: ZipArchive(url: fileURL, mode: .readOnly))
     }
 
+    /// Closes the underlying archive and releases associated resources.
+    ///
+    /// Call this when you are done reading from the package to ensure resources are freed promptly.
     func invalidate() {
         archive.close()
     }
 }
 
 public extension PackageReader<Data> {
+    /// Creates a reader that opens a 3MF package from in‑memory data.
+    ///
+    /// - Parameter data: The 3MF package data.
+    /// - Throws: An error if the archive cannot be opened.
     init(data: Data) throws {
         try self.init(archive: ZipArchive(data: data))
     }
@@ -58,10 +80,20 @@ internal extension PackageReader {
 }
 
 public extension PackageReader {
+    /// Loads and parses a 3MF model from the package.
+    ///
+    /// - Parameter path: The URL of a specific model within the package. If `nil`, the package's root model is loaded.
+    /// - Returns: A parsed `Model` instance.
+    /// - Throws: Errors related to reading or parsing the model from the package.
     func model(at path: URL? = nil) throws -> Model {
         return try Model(from: modelRootElement(at: path))
     }
 
+    /// Reads raw data for a file stored within the package.
+    ///
+    /// - Parameter url: The URL of the file within the package (e.g., a texture or auxiliary asset).
+    /// - Returns: The file data if present, or `nil` if the file cannot be found.
+    /// - Throws: An error if the archive cannot be read.
     func readFile(at url: URL) throws -> Data? {
         var filePath = url.path
         if filePath.hasPrefix("/") {

Sources/ThreeMF/Package/PackageWriter.swift

@@ -2,14 +2,29 @@ import Foundation
 import Zip
 import Nodal
 
+/// Writes 3MF packages to either a file URL or in‑memory data, managing models, related files, and relationships.
+///
+/// PackageWriter abstracts the underlying ZIP archive and handles:
+/// - Writing the root model and any additional models
+/// - Adding textures, thumbnails, and other related files with appropriate content types and relationships
+/// - Finalizing to disk (URL) or returning in‑memory Data
+///
+/// Usage:
+/// - Initialize with a URL (for on‑disk output) or with no parameters (for in‑memory output)
+/// - Populate `model` and add any additional files or models
+/// - Call `finalize()` to write the package
+///
 public class PackageWriter<Target> {
     private let archive: ZipArchive<Target>
     private var contentTypes = ContentTypes()
     private var relationships = Relationships()
     private var modelFileRelationships = Relationships()
     private var additionalModels: [String: Model] = [:]
 
+    /// The root model written as the package's primary model.
     public var model = Model()
+
+    /// The compression level used for files added to the package.
     public var compressionLevel = CompressionLevel.default
 
     private init(archive: ZipArchive<Target>) {
@@ -19,30 +34,45 @@ public class PackageWriter<Target> {
 }
 
 public extension PackageWriter<URL> {
+    /// Creates a writer that outputs a 3MF package to a file URL.
+    ///
+    /// - Parameter fileURL: The destination file URL where the 3MF package will be written.
+    /// - Throws: An error if the archive cannot be created or opened for writing.
     convenience init(url fileURL: URL) throws {
         try self.init(archive: ZipArchive(url: fileURL, mode: .overwrite))
     }
 
-    // Write the 3MF file to disk
+    /// Finalizes and writes the 3MF package to disk.
+    ///
+    /// After calling this method, the writer can no longer be used to add files.
+    /// - Throws: An error if writing or finalizing the archive fails.
     func finalize() throws {
         try writeMainFiles()
         try archive.finalize()
     }
 }
 
 public extension PackageWriter<Data> {
+    /// Creates a writer that builds a 3MF package in memory.
     convenience init() {
         self.init(archive: ZipArchive())
     }
 
-    // Generate the 3MF data
+    /// Finalizes and returns the 3MF package as data.
+    ///
+    /// - Returns: The generated 3MF archive data.
+    /// - Throws: An error if writing or finalizing the archive fails.
     func finalize() throws -> Data {
         try writeMainFiles()
         try writeMetaFiles()
         return try archive.finalize()
     }
 
-    // Generate the 3MF data
+    /// Finalizes and returns the 3MF package as data.
+    ///
+    /// This async variant allows preparing files concurrently when needed.
+    /// - Returns: The generated 3MF archive data.
+    /// - Throws: An error if writing or finalizing the archive fails.
     func finalize() async throws -> Data {
         try await writeMainFiles()
         try writeMetaFiles()
@@ -51,6 +81,15 @@ public extension PackageWriter<Data> {
 }
 
 public extension PackageWriter {
+    /// Adds an arbitrary file to the package at the specified URL, with optional content type and relationship metadata.
+    ///
+    /// - Parameters:
+    ///   - url: The destination URL within the package.
+    ///   - mimeType: The file's MIME type to be recorded in content types. Pass `nil` to skip.
+    ///   - relationshipType: An optional relationship type to record. Pass `nil` to skip.
+    ///   - relativeToRootModel: Whether to attach the relationship to the root model file instead of the package root.
+    ///   - data: The file contents.
+    /// - Throws: An error if the file cannot be added to the archive.
     func addFile(
         at url: URL,
         contentType mimeType: String?,
@@ -71,6 +110,12 @@ public extension PackageWriter {
         try addFile(at: url, data: data)
     }
 
+    /// Adds a texture to the package and returns its assigned URL.
+    ///
+    /// The file is numbered automatically and registered with the appropriate content type and relationship.
+    /// - Parameter data: The texture file data.
+    /// - Returns: The URL assigned to the texture within the package.
+    /// - Throws: An error if the file cannot be added.
     func addTexture(data: Data) throws -> URL {
         try addNumberedFile(
             base: "Textures/Texture",
@@ -80,6 +125,14 @@ public extension PackageWriter {
         )
     }
 
+    /// Adds a thumbnail to the package and returns its assigned URL.
+    ///
+    /// The file is numbered automatically and registered with the appropriate content type and relationship.
+    /// - Parameters:
+    ///   - data: The thumbnail image data.
+    ///   - mimeType: The thumbnail image MIME type (e.g., "image/png").
+    /// - Returns: The URL assigned to the thumbnail within the package.
+    /// - Throws: An error if the file cannot be added.
     func addThumbnail(data: Data, mimeType: String) throws -> URL {
         try addNumberedFile(
             base: "Metadata/Thumbnail",
@@ -89,6 +142,14 @@ public extension PackageWriter {
         )
     }
 
+    /// Registers an additional model to be included in the package and returns the URL it will be written to.
+    ///
+    /// If a model with the same name already exists, a numeric suffix is added to ensure uniqueness.
+    /// - Parameters:
+    ///   - model: The additional model to include.
+    ///   - name: The desired base name (without extension) of the model file.
+    /// - Returns: The URL where the model will be written inside the package.
+    /// - Throws: An error if the name is invalid.
     func addAdditionalModel(_ model: Model, named name: String) throws -> URL {
         var name = name
         var counter = 2