Docs: 主要なクラスへコメントを追加

2RiniaR · Nov 30, 2024 · b636c7f · b636c7f
1 parent eb772c0
commit b636c7f
Show file tree

Hide file tree

Showing 32 changed files with 279 additions and 18 deletions.
diff --git a/Common/Discord/DiscordMessagePresenterBase.cs b/Common/Discord/DiscordMessagePresenterBase.cs
@@ -3,8 +3,14 @@
 
 namespace Approvers.King.Common;
 
+/// <summary>
+/// discordのメッセージをトリガーとするイベント
+/// </summary>
 public abstract class DiscordMessagePresenterBase : PresenterBase
 {
+    /// <summary>
+    /// トリガーとなったメッセージ
+    /// </summary>
     public SocketUserMessage Message { get; init; } = null!;
 
     protected override async Task SendAppError(AppException e)

diff --git a/Common/Master/MasterManager.cs b/Common/Master/MasterManager.cs
@@ -2,6 +2,9 @@
 
 namespace Approvers.King.Common;
 
+/// <summary>
+/// マスタデータを管理する
+/// </summary>
 public class MasterManager : Singleton<MasterManager>
 {
 #pragma warning disable CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider declaring as nullable.
@@ -20,6 +23,9 @@ public class MasterManager : Singleton<MasterManager>
 #pragma warning restore CS8618 // Non-nullable field must contain a non-null value when exiting constructor. Consider declaring as nullable.
 #pragma warning restore CS0649 // Field is never assigned to, and will always have its default value
 
+    /// <summary>
+    /// マスタデータをスプレッドシートから読み込んで更新する
+    /// </summary>
     public static async Task FetchAsync()
     {
         var dict = new Dictionary<FieldInfo, string>();

diff --git a/Common/Master/MasterRecord.cs b/Common/Master/MasterRecord.cs
@@ -1,5 +1,8 @@
 namespace Approvers.King.Common;
 
+/// <summary>
+/// マスタデータの行
+/// </summary>
 public abstract class MasterRecord<TKey> where TKey : notnull
 {
     public abstract TKey Key { get; }

diff --git a/Common/Master/MasterTable.cs b/Common/Master/MasterTable.cs
@@ -1,5 +1,9 @@
 namespace Approvers.King.Common;
 
+/// <summary>
+/// マスタデータのテーブル
+/// スプレッドシートのシートに相当
+/// </summary>
 public abstract class MasterTable<TKey, TRecord> where TRecord : MasterRecord<TKey> where TKey : notnull
 {
     private readonly Dictionary<TKey, TRecord> _records = [];

diff --git a/Common/Master/RandomMessageMaster.cs b/Common/Master/RandomMessageMaster.cs
@@ -13,6 +13,9 @@ public enum RandomMessageType
     GachaFailed,
 }
 
+/// <summary>
+/// discordに送信するランダムなメッセージ
+/// </summary>
 [SuppressMessage("ReSharper", "UnassignedGetOnlyAutoProperty")]
 public class RandomMessage : MasterRecord<string>
 {

diff --git a/Common/Master/SettingMaster.cs b/Common/Master/SettingMaster.cs
@@ -35,24 +35,99 @@ private int GetInt(string key)
         return result;
     }
 
+    /// <summary>
+    /// botの返信を遅延させる最大時間(ms)
+    /// </summary>
     public int ReplyMaxDuration => GetInt(nameof(ReplyMaxDuration));
+
+    /// <summary>
+    /// botの返信時に入力中状態にする最大時間(ms)
+    /// </summary>
     public int TypingMaxDuration => GetInt(nameof(TypingMaxDuration));
+
+    /// <summary>
+    /// 毎日リセットの0:00からのオフセット時間(ms)
+    /// </summary>
     public int DailyResetTime => GetInt(nameof(DailyResetTime));
+
+    /// <summary>
+    /// 毎月リセットの日
+    /// </summary>
     public int MonthlyResetDay => GetInt(nameof(MonthlyResetDay));
+
+    /// <summary>
+    /// 創造主の誕生月
+    /// </summary>
     public int BirthdayMonth => GetInt(nameof(BirthdayMonth));
+
+    /// <summary>
+    /// 創造主の誕生日
+    /// </summary>
     public int BirthdayDay => GetInt(nameof(BirthdayDay));
+
+    /// <summary>
+    /// 確率返信の最大確率(千分率)
+    /// </summary>
     public int MaxRareReplyProbabilityPermillage => GetInt(nameof(MaxRareReplyProbabilityPermillage));
+
+    /// <summary>
+    /// 確率返信の抽選単位(千分率)
+    /// </summary>
     public int RareReplyProbabilityStepPermillage => GetInt(nameof(RareReplyProbabilityStepPermillage));
+
+    /// <summary>
+    /// 単発ガチャ1回の価格
+    /// </summary>
     public int PricePerGachaOnce => GetInt(nameof(PricePerGachaOnce));
+
+    /// <summary>
+    /// 10連ガチャ1回の価格
+    /// </summary>
     public int PricePerGachaTenTimes => GetInt(nameof(PricePerGachaTenTimes));
+
+    /// <summary>
+    /// 単発確定ガチャ1回の価格
+    /// </summary>
     public int PricePerGachaOnceCertain => GetInt(nameof(PricePerGachaOnceCertain));
+
+    /// <summary>
+    /// 購入情報表示時の表示ユーザー数
+    /// </summary>
     public int PurchaseInfoRankingViewUserCount => GetInt(nameof(PurchaseInfoRankingViewUserCount));
+
+    /// <summary>
+    /// スロット1回の価格
+    /// </summary>
     public int PricePerSlotOnce => GetInt(nameof(PricePerSlotOnce));
+
+    /// <summary>
+    /// スロット実行時にdiscordに送信するメッセージ上の、リール回転中の絵文字フォーマット
+    /// </summary>
     public string SlotReelRollingFormat => GetString(nameof(SlotReelRollingFormat));
+
+    /// <summary>
+    /// スロット実行時にdiscordに送信するメッセージ上の、レバーの絵文字フォーマット
+    /// </summary>
     public string SlotLeverFormat => GetString(nameof(SlotLeverFormat));
+
+    /// <summary>
+    /// 各ユーザーの1日あたりのスロット実行制限回数
+    /// </summary>
     public int UserSlotExecuteLimitPerDay => GetInt(nameof(UserSlotExecuteLimitPerDay));
+
+    /// <summary>
+    /// スロットの調子の最大値(千分率)
+    /// </summary>
     public int SlotMaxConditionOffsetPermillage => GetInt(nameof(SlotMaxConditionOffsetPermillage));
+
+    /// <summary>
+    /// スロットの調子の最小値(千分率)
+    /// </summary>
     public int SlotMinConditionOffsetPermillage => GetInt(nameof(SlotMinConditionOffsetPermillage));
+
+    /// <summary>
+    /// スロットの次に同じ出目が確定する確率の最大値(千分率)
+    /// </summary>
     public int SlotRepeatPermillageUpperBound => GetInt(nameof(SlotRepeatPermillageUpperBound));
 }
 

diff --git a/Common/Master/SlotItemMaster.cs b/Common/Master/SlotItemMaster.cs
@@ -6,6 +6,9 @@ namespace Approvers.King.Common;
 
 public class SlotItemMaster : MasterTable<string, SlotItem>;
 
+/// <summary>
+/// スロットの出目
+/// </summary>
 [SuppressMessage("ReSharper", "UnassignedGetOnlyAutoProperty")]
 public class SlotItem : MasterRecord<string>
 {
@@ -14,12 +17,21 @@ public class SlotItem : MasterRecord<string>
     [field: MasterStringValue("id")]
     public string Id { get; }
 
+    /// <summary>
+    /// discordに送信する絵文字フォーマット
+    /// </summary>
     [field: MasterStringValue("format")]
     public string Format { get; }
 
+    /// <summary>
+    /// 出目が揃った時の、掛け金に対するキャッシュバック倍率
+    /// </summary>
     [field: MasterIntValue("return_rate_permillage")]
     public int ReturnRatePermillage { get; }
 
+    /// <summary>
+    /// 次に同じ出目が確定する確率(千分率)
+    /// </summary>
     [field: MasterIntValue("repeat_permillage")]
     public int RepeatPermillage { get; }
 }
diff --git a/Common/Master/TriggerPhraseMaster.cs b/Common/Master/TriggerPhraseMaster.cs
@@ -17,6 +17,9 @@ public enum TriggerType
     SlotRanking,
 }
 
+/// <summary>
+/// discordのメッセージからイベントを発動する文言
+/// </summary>
 [SuppressMessage("ReSharper", "UnassignedGetOnlyAutoProperty")]
 public class TriggerPhrase : MasterRecord<string>
 {

diff --git a/Common/Models/AppException.cs b/Common/Models/AppException.cs
@@ -1,3 +1,6 @@
 namespace Approvers.King.Common;
 
+/// <summary>
+/// アプリ内の汎用例外
+/// </summary>
 public class AppException(string message) : Exception(message);
diff --git a/Common/Models/AppService.cs b/Common/Models/AppService.cs
@@ -2,12 +2,19 @@
 
 namespace Approvers.King.Common;
 
+/// <summary>
+/// DB上のデータモデル
+/// </summary>
 public class AppService : DbContext
 {
     public DbSet<AppState> AppStates { get; set; }
     public DbSet<User> Users { get; set; }
     public DbSet<GachaProbability> GachaProbabilities { get; set; }
 
+    /// <summary>
+    /// セッションを作成する
+    /// dbを読み書きする際は、このメソッドを使う
+    /// </summary>
     public static AppService CreateSession()
     {
         return new AppService();
@@ -18,6 +25,9 @@ protected override void OnConfiguring(DbContextOptionsBuilder options)
         options.UseSqlite(EnvironmentManager.SqliteConnectionString);
     }
 
+    /// <summary>
+    /// ユーザーを取得する なければ作成する
+    /// </summary>
     public async Task<User> FindOrCreateUserAsync(ulong discordId)
     {
         var user = await Users.FindAsync(discordId);

diff --git a/Common/Models/AppState.cs b/Common/Models/AppState.cs
@@ -46,6 +46,9 @@ public async static Task SetStringAsync(this DbSet<AppState> source, AppStateTyp
     }
 }
 
+/// <summary>
+/// アプリ全体の状態
+/// </summary>
 public class AppState
 {
     [Key] public AppStateType Type { get; set; }

diff --git a/Common/Models/GachaManager.cs b/Common/Models/GachaManager.cs
@@ -7,17 +7,20 @@ public class GachaManager : Singleton<GachaManager>
     private readonly List<GachaProbability> _replyMessageTable = new();
 
     /// <summary>
-    ///     現在のメッセージに反応する確率
+    /// 現在のメッセージに反応する確率
     /// </summary>
     public float RareReplyRate { get; private set; }
 
     /// <summary>
-    ///     各メッセージの確率
+    /// 各メッセージの確率
     /// </summary>
     public IReadOnlyList<GachaProbability> ReplyMessageTable => _replyMessageTable;
 
     public bool IsTableEmpty => ReplyMessageTable.Count == 0;
 
+    /// <summary>
+    /// 現在の状態を読み込む
+    /// </summary>
     public async Task LoadAsync()
     {
         await using var app = AppService.CreateSession();
@@ -30,6 +33,9 @@ public async Task LoadAsync()
         RareReplyRate = NumberUtility.GetPercentFromPermillage(rareReplyRatePermillage ?? 0);
     }
 
+    /// <summary>
+    /// 現在の状態を保存する
+    /// </summary>
     public async Task SaveAsync()
     {
         await using var app = AppService.CreateSession();
@@ -43,8 +49,12 @@ public async Task SaveAsync()
         await app.SaveChangesAsync();
     }
 
-    public void RefreshMessageTable()
+    /// <summary>
+    /// マスタデータを読み込む
+    /// </summary>
+    public void LoadMaster()
     {
+        // 同じIDのメッセージは確率を保持し、新規追加分は確率0%で初期化する
         var messages = MasterManager.RandomMessageMaster
             .GetAll(x => x.Type == RandomMessageType.GeneralReply)
             .Select(x => new GachaProbability()
@@ -58,12 +68,18 @@ public void RefreshMessageTable()
         _replyMessageTable.AddRange(messages);
     }
 
+    /// <summary>
+    /// 単発ガチャを回す
+    /// </summary>
     public GachaProbability? Roll()
     {
         if (RandomManager.IsHit(RareReplyRate) == false) return null;
         return GetRandomResult();
     }
 
+    /// <summary>
+    /// 確定ガチャを回す
+    /// </summary>
     public GachaProbability RollWithoutNone()
     {
         return GetRandomResult();
@@ -88,17 +104,25 @@ private GachaProbability GetRandomResult()
         return _replyMessageTable[^1];
     }
 
+    /// <summary>
+    /// メッセージに反応する確率を再抽選する
+    /// </summary>
     public void ShuffleRareReplyRate()
     {
+        // 確率は step の単位で max まで変動（ただし0にはならない）
         var step = MasterManager.SettingMaster.RareReplyProbabilityStepPermillage;
         var max = MasterManager.SettingMaster.MaxRareReplyProbabilityPermillage;
         var rates = Enumerable.Range(0, max / step)
             .Select(i => NumberUtility.GetPercentFromPermillage((i + 1) * step));
         RareReplyRate = RandomManager.PickRandom(rates);
     }
 
+    /// <summary>
+    /// 各メッセージの確率を再抽選する
+    /// </summary>
     public void ShuffleMessageRates()
     {
+        // いい感じに確率がばらけるように、カイ二乗分布を適用
         var borders = Enumerable.Range(0, _replyMessageTable.Count - 1)
             .Select(x => (float)Math.Pow(RandomManager.GetRandomFloat(1f), 2))
             .Select(x => (int)Math.Floor(x * 100f))