Skip to content
This repository has been archived by the owner on Feb 1, 2024. It is now read-only.

Commit

Permalink
Cleanup of the XML code documentation(#129)
Browse files Browse the repository at this point in the history
You can use a tool like this to view the documentation outside VS: https://livedocumenter.barryjones.me.uk/
  • Loading branch information
Rnen authored Jul 19, 2022
1 parent 46da5e8 commit fdf5060
Show file tree
Hide file tree
Showing 17 changed files with 411 additions and 181 deletions.
60 changes: 39 additions & 21 deletions AdminToolbox/AdminToolbox/API/ATWeb.cs
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,45 @@ namespace AdminToolbox.API
{
using API.Webhook;
/// <summary>
/// Static <see cref="AdminToolbox"/> class that contains all of the plugin web-based methods
/// Struct used by <see cref="ATWeb.LatestRelease"/> to store the latest GitHub release info
/// </summary>
public struct ATReleaseInfo
{
/// <summary>
/// Title of the release
/// </summary>
public string Title { get; }
/// <summary>
/// Version of the release
/// </summary>
public string Version { get; }
/// <summary>
/// GitHub Author of the release
/// </summary>
public string Author { get; }
/// <summary>
/// Download link for the release
/// </summary>
public string DownloadLink { get; }

/// <summary>
/// Constructor that takes the supplied strings from <see cref="ATWeb.GetOnlineInfo()"/>
/// </summary>
/// <param name="Title">Title of the release</param>
/// <param name="Version">Version of the release</param>
/// <param name="Author">Author of the release</param>
/// <param name="DownloadLink">Download link of the release</param>
internal ATReleaseInfo(string Title, string Version, string Author, string DownloadLink)
{
this.Title = Title;
this.Version = Version;
this.Author = Author;
this.DownloadLink = DownloadLink;
}
}

/// <summary>
/// Static <see cref="AdminToolbox"/> class that contains all of the plugin's web-based methods
/// </summary>
public static class ATWeb
{
Expand All @@ -19,26 +57,6 @@ public static class ATWeb

private const string ApiURL = "https://api.github.com/repos/Rnen/AdminToolbox/releases/latest";

/// <summary>
/// Class for storing the latest GitHub release info
/// </summary>
public struct ATReleaseInfo
{
#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
public string Title { get; }
public string Version { get; }
public string Author { get; }
public string DownloadLink { get; }

public ATReleaseInfo(string Title, string Version, string Author, string DownloadLink)
{
this.Title = Title;
this.Version = Version;
this.Author = Author;
this.DownloadLink = DownloadLink;
}
#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member
}

private static DateTime _lastVersionCheck = DateTime.UtcNow;
private static ATReleaseInfo _latestReleaseInfo = new ATReleaseInfo();
Expand Down
7 changes: 7 additions & 0 deletions AdminToolbox/AdminToolbox/API/ExtentionMethods.cs
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,9 @@ namespace AdminToolbox.API.Extentions
{
using API.Webhook;

/// <summary>
/// Class storing all of the plugin's extensions
/// </summary>
public static class ExtentionMethods
{
private static Server Server => PluginManager.Manager.Server;
Expand Down Expand Up @@ -188,6 +191,8 @@ internal static void Cleanup(this Dictionary<string, PlayerSettings> dict)
/// <summary>
/// Colors the team for the MultiAdmin console window
/// </summary>
/// <param name="player">Player to get the team-color from</param>
/// <returns>Color-formatted team name for use with MultiAdmin</returns>
public static string ToColoredMultiAdminTeam(this Player player)
{
if (!AdminToolbox.isColored)
Expand All @@ -214,6 +219,8 @@ public static string ToColoredMultiAdminTeam(this Player player)
/// <summary>
/// Colors the team for the rich text game windows
/// </summary>
/// <param name="player">Player to get the team-color from</param>
/// <returns>Color-formatted team name for in-game use</returns>
public static string ToColoredRichTextRole(this Player player)
{
switch ((Team)player.PlayerRole.Team)
Expand Down
53 changes: 31 additions & 22 deletions AdminToolbox/AdminToolbox/API/GetFromString.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,19 @@ public static class GetFromString
private static Server Server => PluginManager.Manager.Server;

/// <summary>
/// Returns <see cref ="Player"/> from <see cref="string"/> <paramref name="arg"/>
/// Returns the first found <see cref ="Player"/> from the searched string
/// </summary>
/// <returns><see cref="Player"/></returns>
public static Player GetPlayer(string arg)
/// <param name="searchString">The sting used to search. Can be name, PlayerID or SteamID</param>
/// <returns><see cref="Player"/> or null if player is not found.</returns>
/// <remarks>It is recommended to use <see cref="TryGetPlayer(string, out Player)"/> instead</remarks>
public static Player GetPlayer(string searchString)
{
Player playerOut = null;
if (string.IsNullOrEmpty(arg))
if (string.IsNullOrEmpty(searchString))
return null;
try
{
if (byte.TryParse(arg, out byte pID))
if (byte.TryParse(searchString, out byte pID))
{
foreach (Player pl in Server.GetPlayers())
if (pl.PlayerID == pID)
Expand All @@ -32,7 +34,7 @@ public static Player GetPlayer(string arg)
break;
}
}
else if (long.TryParse(arg, out long ID))
else if (long.TryParse(searchString, out long ID))
{
foreach (Player pl in Server.GetPlayers())
if (pl.UserID.Contains(ID.ToString()))
Expand All @@ -43,7 +45,7 @@ public static Player GetPlayer(string arg)
}
else
{
playerOut = Server.GetPlayers(arg.ToLower()).OrderBy(s => s.Name.Length).FirstOrDefault();
playerOut = Server.GetPlayers(searchString.ToLower()).OrderBy(s => s.Name.Length).FirstOrDefault();
}
}
catch (System.Exception e)
Expand All @@ -54,9 +56,22 @@ public static Player GetPlayer(string arg)
}

/// <summary>
/// Gets list of players from <see cref="string"/> <paramref name="name"/> parameter
/// Tries getting the supplied player from <see cref="GetPlayer(string)"/>.
/// </summary>
/// <returns><see cref="System.Array"/> of <see cref="Player"/></returns>
/// <param name="searchString">The sting used to search. Can be name, PlayerID or SteamID</param>
/// <param name="player">The first <see cref="Player"/> found from the search</param>
/// <returns>Success</returns>
public static bool TryGetPlayer(string searchString, out Player player)
{
player = GetPlayer(searchString);
return player != null;
}

/// <summary>
/// Gets a list of players that has the supplied UserGroup, RankName or BadgeText
/// </summary>
/// <param name="name">Name of <see cref="UserGroup"/>, badge-text or rank-name</param>
/// <returns><see cref="Player"/>[] or null if players with supplied group could not be found.</returns>
public static Player[] GetGroup(string name)
{
if (!name.StartsWith("#"))
Expand All @@ -69,9 +84,10 @@ public static Player[] GetGroup(string name)
}

/// <summary>
/// Gets list of players from <see cref="string"/> <paramref name="name"/> parameter
/// Gets a list of players that has the supplied role
/// </summary>
/// <returns><see cref="System.Array"/> of <see cref="Player"/></returns>
/// <param name="name">Name of <see cref="RoleType"/></param>
/// <returns><see cref="Player"/>[] or null if players with supplied role could not be found.</returns>
public static Player[] GetRole(string name)
{
if (!name.StartsWith("$"))
Expand All @@ -84,9 +100,10 @@ public static Player[] GetRole(string name)
}

/// <summary>
/// Gets list of players from <see cref="string"/> <paramref name="name"/> parameter
/// Gets a list of players that are on the supplied team
/// </summary>
/// <returns><see cref="System.Array"/> of <see cref="Player"/></returns>
/// <param name="name">Name of <see cref="TeamType"/></param>
/// <returns><see cref="Player"/>[] or null if players with supplied team could not be found.</returns>
public static Player[] GetTeam(string name)
{
if (!name.StartsWith("$"))
Expand All @@ -98,14 +115,6 @@ public static Player[] GetTeam(string name)
return null;
}

/// <summary>
/// Attempts to get player from <see cref="GetPlayer(string)"/>.
/// </summary>
/// <returns><see cref ="bool"/> based on success</returns>
public static bool TryGetPlayer(string arg, out Player player)
{
player = GetPlayer(arg);
return player != null;
}

}
}
31 changes: 18 additions & 13 deletions AdminToolbox/AdminToolbox/API/JailHandler.cs
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ namespace AdminToolbox.API
public class JailHandler
{
/// <summary>
/// <see cref ="AdminToolbox"/> jail <see cref="Vector"/> position
/// Jail <see cref="Vector"/> position
/// </summary>
public static Vector JailPos
{
Expand All @@ -25,14 +25,16 @@ public static Vector JailPos
}
}

private JailHandler() { }

private static Server Server => PluginManager.Manager.Server;

private static void Debug(string message) => AdminToolbox.singleton.Debug("[JailHandler]: " + message);
private static void Info(string message) => AdminToolbox.singleton.Info("[JailHandler]: " + message);

/// <summary>
/// Checks the players marked as "Jailed" to see if they are at where they're supposed to be
/// <para> Gets run in the <see cref="MyMiscEvents"/>.cs Update event</para>
/// <para> Gets run in the <see cref="MyMiscEvents"/> update event on a timer</para>
/// </summary>
internal static void CheckJailedPlayers()
{
Expand All @@ -41,28 +43,31 @@ internal static void CheckJailedPlayers()
foreach (Player pl in jailedPlayers)
if (AdminToolbox.ATPlayerDict.ContainsKey(pl.UserID))
if (!pl.IsInsideJail()) SendToJail(pl);
else if (AdminToolbox.ATPlayerDict[pl.UserID].JailedToTime <= DateTime.UtcNow)
else if (AdminToolbox.ATPlayerDict[pl.UserID].JailReleaseTime <= DateTime.UtcNow)
ReturnFromJail(pl);
}

/// <summary>
/// Sends <see cref="Player"/> to jail
/// Sends <see cref="Player"/> to Jail for the remaining previous time, or if that's null, one year
/// </summary>
/// <param name="player">The <see cref="Player"/> to put in Jail</param>
/// <returns>Operation success</returns>
public static bool SendToJail(Player player) => SendToJail(player, null);
/// <summary>
/// Sends <see cref="Player"/> to jail, with time overload. <returns> Returns bool of operation success </returns>
/// Puts <see cref="Player"/> in Jail
/// </summary>
/// <param name="player">the <see cref="Player"/> to send into jail</param>
/// <param name="jailedToTime">the time to jail the player. Null sets the time to remaining time, or if thats null, one year</param>
public static bool SendToJail(Smod2.API.Player player, DateTime? jailedToTime)
/// <param name="player">The <see cref="Player"/> to put in Jail</param>
/// <param name="releaseTime">The release-time of the player. Null sets the time to remaining previous time, or if that's null, one year</param>
/// <returns>Operation success</returns>
public static bool SendToJail(Player player, DateTime? releaseTime)
{
if (player == null || player.PlayerRole.RoleID == Smod2.API.RoleType.SPECTATOR || player.OverwatchMode) return false;
Debug($"Attempting to jail {player.Name}");
if (AdminToolbox.ATPlayerDict.TryGetValue(player.UserID, out PlayerSettings psetting))
{
if (!jailedToTime.HasValue || jailedToTime < DateTime.UtcNow)
if (!releaseTime.HasValue || releaseTime < DateTime.UtcNow)
Debug($"Jail time for \"{player.Name}\" not specified, jailing for a year.");
psetting.JailedToTime = jailedToTime ?? ((psetting.JailedToTime > DateTime.UtcNow) ? psetting.JailedToTime : DateTime.UtcNow.AddYears(1));
psetting.JailReleaseTime = releaseTime ?? ((psetting.JailReleaseTime > DateTime.UtcNow) ? psetting.JailReleaseTime : DateTime.UtcNow.AddYears(1));
//Saves original variables
psetting.originalPos = player.GetPosition();
if (!psetting.isJailed)
Expand Down Expand Up @@ -92,9 +97,9 @@ public static bool SendToJail(Smod2.API.Player player, DateTime? jailedToTime)

/// <summary>
/// Removes <see cref="Player"/> from jail and restored original values/position.
/// <returns> Returns bool of operation success </returns>
/// </summary>
/// <param name="player">the player to return</param>
/// <param name="player"> The <see cref="Player"/> to remove from Jail</param>
/// <returns>Operation success</returns>
public static bool ReturnFromJail(Player player)
{
if (player == null || string.IsNullOrEmpty(player.UserID.Trim()))
Expand All @@ -106,7 +111,7 @@ public static bool ReturnFromJail(Player player)
if (AdminToolbox.ATPlayerDict.TryGetValue(player.UserID, out PlayerSettings psetting))
{
psetting.isJailed = false;
psetting.JailedToTime = DateTime.UtcNow;
psetting.JailReleaseTime = DateTime.UtcNow;
player.ChangeRole(psetting.previousRole, true, false);
player.Teleport(psetting.originalPos, true);
player.Health = psetting.previousHealth;
Expand Down
18 changes: 12 additions & 6 deletions AdminToolbox/AdminToolbox/API/LevenshteinDistance.cs
Original file line number Diff line number Diff line change
@@ -1,16 +1,22 @@
using System;
using System;

namespace AdminToolbox.API
{
/// <summary>
/// Class storing the LevenshteinDistance calculations
/// </summary>
public static class LevenshteinDistance
{
/// <summary>
/// Compute the distance between two <see cref="string"/>s.
/// Compute the distance between two strings
/// </summary>
public static int Compute(string s, string t)
/// <param name="first">String 1</param>
/// <param name="second">String 2</param>
/// <returns>The distance AKA. number of required changes to make the strings equal</returns>
public static int Compute(string first, string second)
{
int n = s.Length;
int m = t.Length;
int n = first.Length;
int m = second.Length;
int[,] d = new int[n + 1, m + 1];

// Step 1
Expand Down Expand Up @@ -40,7 +46,7 @@ public static int Compute(string s, string t)
for (int j = 1; j <= m; j++)
{
// Step 5
int cost = (t[j - 1] == s[i - 1]) ? 0 : 1;
int cost = (second[j - 1] == first[i - 1]) ? 0 : 1;

// Step 6
d[i, j] = Math.Min(
Expand Down
Loading

0 comments on commit fdf5060

Please sign in to comment.