document updates

build/stylecop.json

@@ -5,7 +5,8 @@
       "documentPrivateElements": true,
       "documentPrivateFields": true,
       "excludeFromPunctuationCheck": [
-        "remarks"
+        "remarks",
+        "example"
       ]
     },
     "indentation": {

src/Tgstation.Server.Api/Models/ChatChannel.cs

@@ -14,6 +14,7 @@ public class ChatChannel : ChatChannelBase
 		/// For <see cref="ChatProvider.Irc"/>, it's the IRC channel name and optional password colon separated.
 		/// For <see cref="ChatProvider.Discord"/>, it's the stringified Discord channel snowflake.
 		/// </summary>
+		/// <example>124823852418</example>
 		[Required]
 		[StringLength(Limits.MaximumIndexableStringLength, MinimumLength = 1)]
 		public string? ChannelData { get; set; }

src/Tgstation.Server.Api/Models/EngineVersion.cs

@@ -26,12 +26,14 @@ public sealed class EngineVersion : IEquatable<EngineVersion>
 		/// <summary>
 		/// The <see cref="System.Version"/> of the engine. Currently only valid when <see cref="Engine"/> is <see cref="EngineType.Byond"/>.
 		/// </summary>
+		/// <example>516.1651.0</example>
 		[ResponseOptions]
 		public Version? Version { get; set; }
 
 		/// <summary>
 		/// The git commit SHA of the engine. Currently only valid when <see cref="Engine"/> is <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>caa1e1f400c8b6a535e03cff28cf57f919e9378c</example>
 		[ResponseOptions]
 		[StringLength(Limits.MaximumCommitShaLength, MinimumLength = Limits.MaximumCommitShaLength)]
 		public string? SourceSHA { get; set; }

src/Tgstation.Server.Api/Models/EntityId.cs

@@ -8,6 +8,7 @@ public class EntityId
 		/// <summary>
 		/// The ID of the entity.
 		/// </summary>
+		/// <example>1</example>
 		[RequestOptions(FieldPresence.Required)]
 		[RequestOptions(FieldPresence.Ignored, PutOnly = true)]
 		public virtual long? Id { get; set; }

src/Tgstation.Server.Api/Models/Internal/ChatBotSettings.cs

@@ -16,13 +16,15 @@ public abstract class ChatBotSettings : NamedEntity
 		/// <summary>
 		/// The time interval in minutes the chat bot attempts to reconnect if <see cref="Enabled"/> and disconnected. Must not be zero.
 		/// </summary>
+		/// <example>60</example>
 		[Required]
 		[Range(1, UInt32.MaxValue)]
 		public uint? ReconnectionInterval { get; set; }
 
 		/// <summary>
 		/// The maximum number of <see cref="ChatChannel"/>s the <see cref="ChatBotSettings"/> may contain.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		public ushort? ChannelLimit { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/ChatChannelBase.cs

@@ -10,18 +10,21 @@ public abstract class ChatChannelBase
 		/// <summary>
 		/// If the <see cref="ChatChannel"/> is an admin channel.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? IsAdminChannel { get; set; }
 
 		/// <summary>
 		/// If the <see cref="ChatChannel"/> is a watchdog channel.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? IsWatchdogChannel { get; set; }
 
 		/// <summary>
 		/// If the <see cref="ChatChannel"/> is an updates channel.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? IsUpdatesChannel { get; set; }
 
@@ -34,6 +37,7 @@ public abstract class ChatChannelBase
 		/// <summary>
 		/// A custom tag users can define to group channels together.
 		/// </summary>
+		/// <example>system-channel-only</example>
 		[ResponseOptions]
 		[StringLength(Limits.MaximumStringLength)]
 		public string? Tag { get; set; }

src/Tgstation.Server.Api/Models/Internal/CompileJob.cs

@@ -12,6 +12,7 @@ public abstract class CompileJob : EntityId
 		/// <summary>
 		/// The .dme file used for compilation.
 		/// </summary>
+		/// <example>tgstation.dme</example>
 		[Required]
 		public string? DmeName { get; set; }
 
@@ -36,6 +37,7 @@ public abstract class CompileJob : EntityId
 		/// <summary>
 		/// The DMAPI <see cref="Version"/>.
 		/// </summary>
+		/// <example>7.3.0</example>
 		[NotMapped]
 		[ResponseOptions]
 		public virtual Version? DMApiVersion { get; set; }

src/Tgstation.Server.Api/Models/Internal/DreamDaemonApiBase.cs

@@ -10,6 +10,7 @@ public abstract class DreamDaemonApiBase : DreamDaemonSettings
 		/// <summary>
 		/// An incrementing ID for representing current server execution.
 		/// </summary>
+		/// <example>1</example>
 		[ResponseOptions]
 		public long? SessionId { get; set; }
 
@@ -22,12 +23,14 @@ public abstract class DreamDaemonApiBase : DreamDaemonSettings
 		/// <summary>
 		/// The last known count of connected players. Requires <see cref="DreamDaemonLaunchParameters.HealthCheckSeconds"/> to not be 0 and a game server interop version >= 5.10.0 to populate.
 		/// </summary>
+		/// <example>30</example>
 		[ResponseOptions]
 		public uint? ClientCount { get; set; }
 
 		/// <summary>
 		/// If the server is undergoing a soft reset. This may be automatically set by changes to other fields.
 		/// </summary>
+		/// <example>false</example>
 		[ResponseOptions]
 		public bool? SoftRestart { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/DreamDaemonLaunchParameters.cs

@@ -11,6 +11,7 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// If the BYOND web client can be used to connect to the game server. No-op for <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		[ResponseOptions]
 		public bool? AllowWebClient { get; set; }
@@ -25,6 +26,7 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The <see cref="DreamDaemonVisibility"/> level of DreamDaemon. No-op for <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>2</example>
 		[Required]
 		[ResponseOptions]
 		[EnumDataType(typeof(DreamDaemonVisibility))]
@@ -33,6 +35,7 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The <see cref="DreamDaemonSecurity"/> level of DreamDaemon. No-op for <see cref="EngineType.OpenDream"/>.
 		/// </summary>
+		/// <example>1</example>
 		[Required]
 		[ResponseOptions]
 		[EnumDataType(typeof(DreamDaemonSecurity))]
@@ -41,6 +44,7 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The port DreamDaemon uses. This should be publically accessible.
 		/// </summary>
+		/// <example>1337</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt16.MaxValue)]
@@ -49,13 +53,15 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The port used by <see cref="EngineType.OpenDream"/> for its topic port.
 		/// </summary>
+		/// <example>2337</example>
 		[Required]
 		[ResponseOptions]
 		public ushort? OpenDreamTopicPort { get; set; }
 
 		/// <summary>
 		/// The DreamDaemon startup timeout in seconds.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt32.MaxValue)]
@@ -64,6 +70,7 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The number of seconds between each watchdog health check. 0 disables.
 		/// </summary>
+		/// <example>5</example>
 		[Required]
 		[ResponseOptions]
 		public uint? HealthCheckSeconds { get; set; }
@@ -78,6 +85,7 @@ public class DreamDaemonLaunchParameters
 		/// <summary>
 		/// The timeout for sending and receiving BYOND topics in milliseconds.
 		/// </summary>
+		/// <example>500</example>
 		[Required]
 		[ResponseOptions]
 		[Range(1, UInt32.MaxValue)]

src/Tgstation.Server.Api/Models/Internal/Job.cs

@@ -20,6 +20,7 @@ public class Job : EntityId
 		/// English description of the <see cref="Job"/>.
 		/// </summary>
 		/// <remarks>May not match the <see cref="System.ComponentModel.DescriptionAttribute"/> listed on the <see cref="Models.JobCode"/>.</remarks>
+		/// <example>Installing and configuring important objects.</example>
 		[Required]
 		public string? Description { get; set; }
 
@@ -50,6 +51,7 @@ public class Job : EntityId
 		/// <summary>
 		/// If the <see cref="Job"/> was cancelled.
 		/// </summary>
+		/// <example>false</example>
 		[Required]
 		public bool? Cancelled { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/ServerInformationBase.cs

@@ -10,26 +10,31 @@ public abstract class ServerInformationBase
 		/// <summary>
 		/// Minimum length of database user passwords.
 		/// </summary>
+		/// <example>20</example>
 		public uint MinimumPasswordLength { get; set; }
 
 		/// <summary>
 		/// The maximum number of <see cref="Instance"/>s allowed.
 		/// </summary>
+		/// <example>100</example>
 		public uint InstanceLimit { get; set; }
 
 		/// <summary>
 		/// The maximum number of users allowed.
 		/// </summary>
+		/// <example>100</example>
 		public uint UserLimit { get; set; }
 
 		/// <summary>
 		/// The maximum number of user groups allowed.
 		/// </summary>
+		/// <example>50</example>
 		public uint UserGroupLimit { get; set; }
 
 		/// <summary>
 		/// Limits the locations instances may be created or attached from.
 		/// </summary>
+		/// <example>["/home/tgstation-server/my-server-1", "/home/tgstation-server/my-server-2"]</example>
 		[ResponseOptions]
 		public List<string>? ValidInstancePaths { get; set; }
 	}

src/Tgstation.Server.Api/Models/Internal/SwarmServer.cs

@@ -22,6 +22,7 @@ public abstract class SwarmServer
 		/// <summary>
 		/// The server's identifier.
 		/// </summary>
+		/// <example>myserver-us-east</example>
 		[Required]
 		public string? Identifier { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/SwarmServerInformation.cs

@@ -10,6 +10,7 @@ public class SwarmServerInformation : SwarmServer
 		/// <summary>
 		/// If the <see cref="SwarmServerResponse"/> is the controller.
 		/// </summary>
+		/// <example>false</example>
 		public bool Controller { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Internal/TestMergeApiBase.cs

@@ -11,6 +11,7 @@ public class TestMergeApiBase : TestMergeModelBase
 		/// <summary>
 		/// The ID of the <see cref="TestMergeApiBase"/>.
 		/// </summary>
+		/// <example>1</example>
 		public long Id { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/Internal/TestMergeModelBase.cs

@@ -11,18 +11,21 @@ public abstract class TestMergeModelBase : TestMergeParameters
 		/// <summary>
 		/// The title of the test merge source.
 		/// </summary>
+		/// <example>Fixes and Breaks everything</example>
 		[Required]
 		public string? TitleAtMerge { get; set; }
 
 		/// <summary>
 		/// The body of the test merge source.
 		/// </summary>
+		/// <example># GitHub markdown\n\rI assume?</example>
 		[Required]
 		public string? BodyAtMerge { get; set; }
 
 		/// <summary>
 		/// The URL of the test merge source.
 		/// </summary>
+		/// <example>https://github.com/tgstation/tgstation/pull/31026</example>
 		[Required]
 #pragma warning disable CA1056 // Uri properties should not be strings
 		public string? Url { get; set; }
@@ -31,6 +34,7 @@ public abstract class TestMergeModelBase : TestMergeParameters
 		/// <summary>
 		/// The author of the test merge source.
 		/// </summary>
+		/// <example>MrStonedOne</example>
 		[Required]
 		public string? Author { get; set; }
 

src/Tgstation.Server.Api/Models/Internal/UpdateInformation.cs

@@ -10,6 +10,7 @@ public class UpdateInformation
 		/// <summary>
 		/// The latest available version of the Tgstation.Server.Host assembly from the upstream repository. If <see cref="Version.Major"/> is less than 4 the update cannot be applied due to API changes.
 		/// </summary>
+		/// <example>1.0.0</example>
 		public Version? LatestVersion { get; set; }
 
 		/// <summary>

src/Tgstation.Server.Api/Models/NamedEntity.cs

@@ -10,6 +10,7 @@ public abstract class NamedEntity : EntityId
 		/// <summary>
 		/// The name of the entity represented by the <see cref="NamedEntity"/>.
 		/// </summary>
+		/// <example>MyThingyName</example>
 		[Required]
 		[RequestOptions(FieldPresence.Required, PutOnly = true)]
 		[StringLength(Limits.MaximumIndexableStringLength, MinimumLength = 1)]

src/Tgstation.Server.Api/Models/Request/ServerUpdateRequest.cs

@@ -10,6 +10,7 @@ public sealed class ServerUpdateRequest
 		/// <summary>
 		/// Changes the version of tgstation-server to the given version from the upstream repository.
 		/// </summary>
+		/// <example>6.12.3</example>
 		[RequestOptions(FieldPresence.Required)]
 		public Version? NewVersion { get; set; }
 

src/Tgstation.Server.Api/Models/Response/AdministrationResponse.cs

@@ -12,6 +12,7 @@ public sealed class AdministrationResponse : UpdateInformation
 		/// <summary>
 		/// The GitHub repository the server is built to receive updates from.
 		/// </summary>
+		/// <example>https://github.com/tgstation/tgstation</example>
 		public Uri? TrackedRepositoryUrl { get; set; }
 	}
 }

src/Tgstation.Server.Api/Models/Response/DreamDaemonResponse.cs

@@ -24,45 +24,52 @@ public sealed class DreamDaemonResponse : DreamDaemonApiBase
 		/// <summary>
 		/// The current <see cref="WatchdogStatus"/>.
 		/// </summary>
+		/// <example>2</example>
 		[EnumDataType(typeof(WatchdogStatus))]
 		[ResponseOptions]
 		public WatchdogStatus? Status { get; set; }
 
 		/// <summary>
 		/// The current <see cref="DreamDaemonSecurity"/>. May be upgraded. due to requirements of <see cref="ActiveCompileJob"/>.
 		/// </summary>
+		/// <example>1</example>
 		[EnumDataType(typeof(DreamDaemonSecurity))]
 		[ResponseOptions]
 		public DreamDaemonSecurity? CurrentSecurity { get; set; }
 
 		/// <summary>
 		/// The current <see cref="DreamDaemonVisibility"/>.
 		/// </summary>
+		/// <example>2</example>
 		[EnumDataType(typeof(DreamDaemonVisibility))]
 		[ResponseOptions]
 		public DreamDaemonVisibility? CurrentVisibility { get; set; }
 
 		/// <summary>
 		/// The port the running <see cref="DreamDaemonResponse"/> instance is set to.
 		/// </summary>
+		/// <example>1337</example>
 		[ResponseOptions]
 		public ushort? CurrentPort { get; set; }
 
 		/// <summary>
 		/// The <see cref="EngineType.OpenDream"/> topic port the running <see cref="DreamDaemonResponse"/> instance is set to.
 		/// </summary>
+		/// <example>3000</example>
 		[ResponseOptions]
 		public ushort? CurrentTopicPort { get; set; }
 
 		/// <summary>
 		/// The webclient status the running <see cref="DreamDaemonResponse"/> instance is set to.
 		/// </summary>
+		/// <example>false</example>
 		[ResponseOptions]
 		public bool? CurrentAllowWebclient { get; set; }
 
 		/// <summary>
 		/// The amount of RAM in use by the game server in bytes.
 		/// </summary>
+		/// <example>1073741824</example>
 		[ResponseOptions]
 		public long? ImmediateMemoryUsage { get; set; }
 	}

src/Tgstation.Server.Api/Models/Response/ErrorMessageResponse.cs

@@ -13,16 +13,19 @@ public sealed class ErrorMessageResponse
 		/// <summary>
 		/// The version of the API the server is using.
 		/// </summary>
+		/// <example>9.3.0</example>
 		public Version? ServerApiVersion { get; set; }
 
 		/// <summary>
-		/// A human readable description of the error.
+		/// A human-readable description of the error.
 		/// </summary>
+		/// <example>Ooopsie, we did a fucky wucky!</example>
 		public string? Message { get; set; }
 
 		/// <summary>
 		/// Additional data associated with the error message.
 		/// </summary>
+		/// <example>Error at thing.app.dependency.class.function in line 32</example>
 		[ResponseOptions]
 		public string? AdditionalData { get; set; }