From 74da4abb6224ddebd8b5915d1926f0fc82324e2c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=9C=A8=20Audrey=20=E2=9C=A8?= <audrey@audreyality.com>
Date: Tue, 1 Jul 2025 08:35:55 -0400
Subject: [PATCH] document send response converters

---
 .../Tools/Models/Request/SendRequestModel.cs  | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/src/Api/Tools/Models/Request/SendRequestModel.cs b/src/Api/Tools/Models/Request/SendRequestModel.cs
index 941fa14cfa..c15a3c4da9 100644
--- a/src/Api/Tools/Models/Request/SendRequestModel.cs
+++ b/src/Api/Tools/Models/Request/SendRequestModel.cs
@@ -109,6 +109,12 @@ public class SendRequestModel
     /// </summary>
     public bool? HideEmail { get; set; }
 
+    /// <summary>
+    /// Transforms the request into a send object.
+    /// </summary>
+    /// <param name="userId">The user that owns the send.</param>
+    /// <param name="sendAuthorizationService">Hashes the send password.</param>
+    /// <returns>The send object</returns>
     public Send ToSend(Guid userId, ISendAuthorizationService sendAuthorizationService)
     {
         var send = new Send
@@ -120,8 +126,17 @@ public class SendRequestModel
         return send;
     }
 
+    /// <summary>
+    /// Transforms the request into a send object and file data.
+    /// </summary>
+    /// <param name="userId">The user that owns the send.</param>
+    /// <param name="fileName">Name of the file uploaded with the send.</param>
+    /// <param name="sendAuthorizationService">Hashes the send password.</param>
+    /// <returns>The send object and file data.</returns>
     public (Send, SendFileData) ToSend(Guid userId, string fileName, ISendAuthorizationService sendAuthorizationService)
     {
+        // FIXME: This method does two things: creates a send and a send file data.
+        //        It should only do one thing.
         var send = ToSendBase(new Send
         {
             Type = Type,
@@ -131,6 +146,13 @@ public class SendRequestModel
         return (send, data);
     }
 
+    /// <summary>
+    /// Update a send object with request content
+    /// </summary>
+    /// <param name="existingSend">The send to update</param>
+    /// <param name="sendAuthorizationService">Hashes the send password.</param>
+    /// <returns>The send object</returns>
+    // FIXME: rename to `UpdateSend`
     public Send ToSend(Send existingSend, ISendAuthorizationService sendAuthorizationService)
     {
         existingSend = ToSendBase(existingSend, sendAuthorizationService);