Improve multer documentation

...

Author: helje5

Sources/multer/File.swift

@@ -10,6 +10,11 @@ import struct MacroCore.Buffer
 
 public extension multer {
 
+  /**
+   * Represents a file that got uploaded by ``multer``. It carries the field
+   * name, the filename, the mime type, and if the ``MemoryStorage`` was used,
+   * the file contents.
+   */
   final class File: Equatable {
 
     /// Name in form field
@@ -39,6 +44,17 @@ public extension multer {
      */
     public var buffer : Buffer?
 
+    /**
+     * Create a new multer file object.
+     * 
+     * - Parameters:
+     *   - fieldName:    Name of the form field that contains the file
+     *   - originalName: Name of file (filename in content-disposition)
+     *   - mimeType:     MIME type of the file, defaults to octet-stream if n/a.
+     *   - path:         Path to stored file on the server, if used w/ disk 
+     *                   storage.
+     *   - buffer:       Contents of file, if loaded into memory.
+     */
     @inlinable
     public init(fieldName    : String,
                 originalName : String,

Sources/multer/Limits.swift

@@ -3,11 +3,17 @@
 //  MacroExpress / multer
 //
 //  Created by Helge Heß on 30/05/16.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2025 ZeeZide GmbH. All rights reserved.
 //
 
 public extension multer {
 
+  /**
+   * Upload limits configuration for multer.
+   * 
+   * This allows to configure file size or count limits. And various other 
+   * limits.
+   */
   struct Limits {
 
     /// Maximum size of field names (100 bytes)
@@ -29,6 +35,22 @@ public extension multer {
     /// Note: This is not checked yet.
     public var headerPairs   : Int? = 2000
 
+    /**
+     * Create a new multer limits configuration.
+     * 
+     * All parameters are optional, defaults:
+     * - field name size: 100
+     * - field size:      1MB
+     * - header pairs:    2000
+     * 
+     * - Parameters:
+     *   - fieldNameSize: Maximum size of field names (100 bytes)
+     *   - fieldSize:     Maximum size of field value (1MB)
+     *   - fields:        Maximum number of non-file fields (unlimited)
+     *   - fileSize:      Max file size (unlimited)
+     *   - files:         Maximum number of file fields (unlimited)
+     *   - headerPairs:   Maximum number of header fields (2000)
+     */
     public init(fieldNameSize : Int? = 100,
                 fieldSize     : Int? = 1024 * 1024,
                 fields        : Int? = nil,

Sources/multer/MemoryStorage.swift

@@ -3,14 +3,19 @@
 //  MacroExpress / multer
 //
 //  Created by Helge Heß on 30/05/16.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2025 ZeeZide GmbH. All rights reserved.
 //
 
 import struct MacroCore.Buffer
 
 extension multer {
 
+  /**
+   * A ``MulterStorage`` that writes the file contents to the ``File/buffer``
+   * property of the ``File`` object, i.e. stores it in-memory.
+   */
   open class MemoryStorage: MulterStorage {
+    // TBD: does this have to be a class?
 
     public init() {}
 

Sources/multer/Middleware.swift

@@ -17,10 +17,10 @@ public extension multer {
    *
    * There are multiple convenience methods to restrict the set of fields to
    * accept:
-   * - `single(fieldName)` (accept just one file for the specified name)
-   * - `array(fieldName)`  (accept just multiple files for the specified name)
-   * - `none`              (accept no file, just form regular fields)
-   * - `any`               (accept all files, careful!)
+   * - ``single(_:)``:  accept just one file for the specified name
+   * - ``array(_:_:)``: accept just multiple files for the specified name
+   * - ``none()``:      accept no file, just form regular fields
+   * - ``any()``:       accept all files, careful!
    *
    * All convenience methods call into this middleware.
    *

Sources/multer/Multer.swift

@@ -3,7 +3,7 @@
 //  MacroExpress / multer
 //
 //  Created by Helge Heß on 30/05/16.
-//  Copyright © 2021 ZeeZide GmbH. All rights reserved.
+//  Copyright © 2021-2025 ZeeZide GmbH. All rights reserved.
 //
 
 import MacroCore
@@ -15,18 +15,29 @@ import connect
  * Middleware to parse `multipart/form-data` payloads.
  *
  * E.g. files submitted using an HTML form like:
- *
- *     <form action="/upload" method="POST" enctype="multipart/form-data">
- *       <input type="file" name="file" multiple="multiple" />
- *       <input type="submit" value="Upload" />
- *     </form>
+ * ```html
+ * <form action="/upload" method="POST" enctype="multipart/form-data">
+ *   <input type="file" name="file" multiple="multiple" />
+ *   <input type="submit" value="Upload" />
+ * </form>
+ * ```
  *
  * Roughly designed after the Node
  * [multer](https://github.com/expressjs/multer#readme)
  * package.
  */
 public struct multer {
 
+  /**
+   * A function that controls what files should be uploaded or skipped.
+   * 
+   * This can be passed to a multer-init. The function gets the
+   * `IncomingMessage`, the ``File`` and a callback that it **must** invoke to
+   * continue multer processing.
+   * 
+   * The filter can issue an error by passing on into the error parameter of the
+   * callback. And it can pass in `true` or `false` to accept or reject a file.
+   */
   public typealias FileFilter =
     ( IncomingMessage, File, @escaping ( Swift.Error?, Bool ) -> Bool ) -> Void
 
@@ -53,6 +64,20 @@ public struct multer {
   }
   #endif
 
+  /**
+   * Create a new multer configuration.
+   * 
+   * This accepts a ``MulterStorage``, ``Limits-swift.struct`` and
+   * a ``FileFilter-swift.typealias``.
+   * All of which are optional. The default storage is the ``MemoryStorage``.
+   * 
+   * - Parameters:
+   *   - storage:    Where to put uploaded files, defaults to ``MemoryStorage``
+   *   - limits:     What ``Limits-swift.struct`` to apply, checks the 
+   *                 documentation for the defaults.
+   *   - fileFilter: A function that can filter what files should be uploaded,
+   *                 defaults to "no filter", i.e. accept all files.
+   */
   @inlinable
   public init(storage    : MulterStorage? = nil,
               limits     : Limits         = Limits(),
@@ -61,12 +86,18 @@ public struct multer {
     self.dest       = nil
     self.fileFilter = fileFilter
     self.limits     = limits
-    self.storage    = storage ?? MemoryStorage()
+    self.storage    = storage ?? multer.memoryStorage()
   }
 }
 
 public extension multer { // MARK: - Storage Factory
 
+  /**
+   * Returns a multer storage that writes the file contents to the 
+   * ``File/buffer`` property of the ``File`` object, i.e. stores it in-memory.
+   * 
+   * - Returns: A new ``MemoryStorage`` object.
+   */
   @inlinable
   static func memoryStorage() -> MemoryStorage {
     return MemoryStorage()

Sources/multer/README.md

@@ -19,6 +19,23 @@ package.
 
 **Note**: DiskStorage is prepared, but not working yet.
 
+### Example
+
+[Examples](https://github.com/Macro-swift/Examples/blob/main/Sources/express-simple/main.swift#L48)
+```swift
+app.post("/multer", multer().array("file", 10)) { req, res, _ in
+    req.log.info("Got files:", req.files["file"])
+    res.render("multer", [
+      "files": req.files["file"]?.map {
+         [ "name":     $0.originalName,
+           "size":     $0.buffer?.length ?? 0,
+           "mimeType": $0.mimeType ]
+      } ?? [],
+      "hasFiles": !(req.files["file"]?.isEmpty ?? true)
+    ])
+}
+```
+
 
 ### Links