Tools - Make Entities and Repositories nullable (#3313)

* support nullability in tools' entities and repositories

* enables C# nullability checks in these files
* includes documentation for affected files

* refine documentation per code review

* improve comments on SendFileData structure

* fix ReferenceEvent.MaxAccessCount documentation

* add value notation to SendFileData.FileName

src/Core/Tools/Models/Data/SendData.cs

@@ -1,15 +1,33 @@
-namespace Bit.Core.Tools.Models.Data;
+#nullable enable
 
+namespace Bit.Core.Tools.Models.Data;
+
+/// <summary>
+/// Shared data for a send
+/// </summary>
 public abstract class SendData
 {
+    /// <summary>
+    /// Instantiates a <see cref="SendData"/>.
+    /// </summary>
     public SendData() { }
 
-    public SendData(string name, string notes)
+    /// <inheritdoc cref="SendData()" />
+    /// <param name="name">User-provided name of the send.</param>
+    /// <param name="notes">User-provided private notes of the send.</param>
+    public SendData(string name, string? notes)
     {
         Name = name;
         Notes = notes;
     }
 
-    public string Name { get; set; }
-    public string Notes { get; set; }
+    /// <summary>
+    /// User-provided name of the send.
+    /// </summary>
+    public string Name { get; set; } = string.Empty;
+
+    /// <summary>
+    /// User-provided private notes of the send.
+    /// </summary>
+    public string? Notes { get; set; } = null;
 }

src/Core/Tools/Models/Data/SendFileData.cs

@@ -1,22 +1,64 @@
-using System.Text.Json.Serialization;
+#nullable enable
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using static System.Text.Json.Serialization.JsonNumberHandling;
 
 namespace Bit.Core.Tools.Models.Data;
 
+/// <summary>
+/// A file secret being sent.
+/// </summary>
 public class SendFileData : SendData
 {
+    /// <summary>
+    /// Instantiates a <see cref="SendFileData"/>.
+    /// </summary>
     public SendFileData() { }
 
-    public SendFileData(string name, string notes, string fileName)
+    /// <inheritdoc cref="SendFileData()"/>
+    /// <param name="name">Attached file name.</param>
+    /// <param name="notes">User-provided private notes of the send.</param>
+    /// <param name="fileName">Attached file name.</param>
+    public SendFileData(string name, string? notes, string fileName)
         : base(name, notes)
     {
         FileName = fileName;
     }
 
-    // We serialize Size as a string since JSON (or Javascript) doesn't support full precision for long numbers
-    [JsonNumberHandling(JsonNumberHandling.WriteAsString | JsonNumberHandling.AllowReadingFromString)]
+    /// <summary>
+    /// Size of the attached file in bytes.
+    /// </summary>
+    /// <remarks>
+    /// Serialized as a string since JSON (or Javascript)  doesn't support
+    /// full precision for long numbers
+    /// </remarks>
+    [JsonNumberHandling(WriteAsString | AllowReadingFromString)]
     public long Size { get; set; }
 
-    public string Id { get; set; }
-    public string FileName { get; set; }
+    /// <summary>
+    /// Uniquely identifies an uploaded file.
+    /// </summary>
+    /// <value>
+    /// Should contain <see langword="null" /> only when a file
+    /// upload is pending. Should never contain null once the
+    /// file upload completes.
+    /// </value>
+    [DisallowNull]
+    public string? Id { get; set; }
+
+    /// <summary>
+    /// Attached file name.
+    /// </summary>
+    /// <value>
+    /// Should contain a non-empty string once the file upload completes.
+    /// </value>
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// When true the uploaded file's length was confirmed within
+    /// the expected tolerance and below the maximum supported
+    /// file size.
+    /// </summary>
     public bool Validated { get; set; } = true;
 }

src/Core/Tools/Models/Data/SendTextData.cs

@@ -1,16 +1,42 @@
-namespace Bit.Core.Tools.Models.Data;
+#nullable enable
 
+namespace Bit.Core.Tools.Models.Data;
+
+/// <summary>
+/// A text secret being sent.
+/// </summary>
 public class SendTextData : SendData
 {
+    /// <summary>
+    /// Instantiates a <see cref="SendTextData"/>.
+    /// </summary>
     public SendTextData() { }
 
-    public SendTextData(string name, string notes, string text, bool hidden)
+    /// <inheritdoc cref="SendTextData()"/>
+    /// <param name="name">Attached file name.</param>
+    /// <param name="notes">User-provided private notes of the send.</param>
+    /// <param name="text">The secret being sent.</param>
+    /// <param name="hidden">
+    /// Indicates whether the secret should be concealed when opening the send.
+    /// </param>
+    public SendTextData(string name, string? notes, string? text, bool hidden)
         : base(name, notes)
     {
         Text = text;
         Hidden = hidden;
     }
 
-    public string Text { get; set; }
+    /// <summary>
+    /// The secret being sent.
+    /// </summary>
+    public string? Text { get; set; }
+
+    /// <summary>
+    /// Indicates whether the secret should be concealed when opening the send.
+    /// </summary>
+    /// <value>
+    /// <see langword="true" /> when the secret should be concealed.
+    /// Otherwise <see langword="false" />.
+    /// </value>
     public bool Hidden { get; set; }
 }