From 9fb87079a31ebec97248b1e4d01b37c66a48f746 Mon Sep 17 00:00:00 2001 From: "Nuno \"Omega Leo\" Diogo" Date: Sun, 14 Dec 2025 15:36:34 +0000 Subject: [PATCH] new documentation changes --- .../OmegaLeo.HelperLib.Changelog.csproj | 2 +- ...OmegaLeo.HelperLib.ChangelogHandler.csproj | 1 + .../Program.cs | 1 + .../Extensions/ListExtensions.cs | 11 ++++++ .../Handlers/DelayedActionHandler.cs | 8 +++++ .../OmegaLeo.HelperLib.Git.csproj | 2 +- .../OmegaLeo.HelperLib.Web.csproj | 3 +- .../Views/Home/Library.cshtml | 17 +++++++++- .../Views/Shared/_Layout.cshtml | 14 ++++---- OmegaLeo.HelperLib.Web/wwwroot/css/site.css | 18 ++++++++++ OmegaLeo.HelperLib.sln.DotSettings.user | 1 + .../Helpers/BenchmarkUtility.cs | 34 +++++++++++++++++++ OmegaLeo.HelperLib/OmegaLeo.HelperLib.csproj | 2 +- 13 files changed, 103 insertions(+), 11 deletions(-) diff --git a/OmegaLeo.HelperLib.Changelog/OmegaLeo.HelperLib.Changelog.csproj b/OmegaLeo.HelperLib.Changelog/OmegaLeo.HelperLib.Changelog.csproj index 866d986..5d96c11 100644 --- a/OmegaLeo.HelperLib.Changelog/OmegaLeo.HelperLib.Changelog.csproj +++ b/OmegaLeo.HelperLib.Changelog/OmegaLeo.HelperLib.Changelog.csproj @@ -25,7 +25,7 @@ - + diff --git a/OmegaLeo.HelperLib.ChangelogHandler/OmegaLeo.HelperLib.ChangelogHandler.csproj b/OmegaLeo.HelperLib.ChangelogHandler/OmegaLeo.HelperLib.ChangelogHandler.csproj index e62e50e..5550538 100644 --- a/OmegaLeo.HelperLib.ChangelogHandler/OmegaLeo.HelperLib.ChangelogHandler.csproj +++ b/OmegaLeo.HelperLib.ChangelogHandler/OmegaLeo.HelperLib.ChangelogHandler.csproj @@ -9,6 +9,7 @@ + diff --git a/OmegaLeo.HelperLib.ChangelogHandler/Program.cs b/OmegaLeo.HelperLib.ChangelogHandler/Program.cs index 9c7dfa1..ec00c21 100644 --- a/OmegaLeo.HelperLib.ChangelogHandler/Program.cs +++ b/OmegaLeo.HelperLib.ChangelogHandler/Program.cs @@ -14,6 +14,7 @@ var changelogs = new Dictionary() { {Path.Join(root, "OmegaLeo.HelperLib.Changelog", "CHANGELOG.md"), typeof(Changelog).Assembly}, {Path.Join(root, "OmegaLeo.HelperLib", "CHANGELOG.md"), typeof(BenchmarkUtility).Assembly}, + {Path.Join(root, "OmegaLeo.HelperLib.Game", "CHANGELOG.md"), typeof(OmegaLeo.HelperLib.Game.Models.ConsoleCommand).Assembly}, }; foreach (var changelog in changelogs) diff --git a/OmegaLeo.HelperLib.Game/Extensions/ListExtensions.cs b/OmegaLeo.HelperLib.Game/Extensions/ListExtensions.cs index 6e90296..21dc8db 100644 --- a/OmegaLeo.HelperLib.Game/Extensions/ListExtensions.cs +++ b/OmegaLeo.HelperLib.Game/Extensions/ListExtensions.cs @@ -1,10 +1,21 @@ using System.Collections.Generic; +using NetFlow.DocumentationHelper.Library.Attributes; using OmegaLeo.HelperLib.Game.Models; namespace OmegaLeo.HelperLib.Game.Extensions { public static class ListExtensions { + [Documentation(nameof(Shuffle), + "Shuffles the elements of the list in place using the provided RandomNumberGenerator.", + null, + @"```csharp +var list = new List { 1, 2, 3, 4}; +var rng = new RandomNumberGenerator(); +// List before: [1, 2, 3, 4] +list.Shuffle(rng); +// List after: [3, 1, 4, 2] (example output) +```")] public static void Shuffle(this IList list, RandomNumberGenerator rng) { for (int i = list.Count - 1; i > 0; i--) diff --git a/OmegaLeo.HelperLib.Game/Handlers/DelayedActionHandler.cs b/OmegaLeo.HelperLib.Game/Handlers/DelayedActionHandler.cs index eb5b4b3..f59fc03 100644 --- a/OmegaLeo.HelperLib.Game/Handlers/DelayedActionHandler.cs +++ b/OmegaLeo.HelperLib.Game/Handlers/DelayedActionHandler.cs @@ -1,7 +1,12 @@ +using NetFlow.DocumentationHelper.Library.Attributes; using OmegaLeo.HelperLib.Game.Models; namespace OmegaLeo.HelperLib.Game.Handlers { + [Documentation(nameof(DelayedActionHandler), "Handler for managing delayed actions, allowing cancellation and status checking.", null, @"```csharp +var action = new DelayedAction(...); +var handler = new DelayedActionHandler(action); +```")] public class DelayedActionHandler { private readonly DelayedAction _action; @@ -11,6 +16,9 @@ namespace OmegaLeo.HelperLib.Game.Handlers _action = action; } + [Documentation(nameof(Cancel), "Cancels the delayed action if it has not yet executed.", null, @"```csharp +handler.Cancel(); +```")] public void Cancel() { if (_action != null) diff --git a/OmegaLeo.HelperLib.Git/OmegaLeo.HelperLib.Git.csproj b/OmegaLeo.HelperLib.Git/OmegaLeo.HelperLib.Git.csproj index c149dcf..03d8ca0 100644 --- a/OmegaLeo.HelperLib.Git/OmegaLeo.HelperLib.Git.csproj +++ b/OmegaLeo.HelperLib.Git/OmegaLeo.HelperLib.Git.csproj @@ -13,7 +13,7 @@ - + diff --git a/OmegaLeo.HelperLib.Web/OmegaLeo.HelperLib.Web.csproj b/OmegaLeo.HelperLib.Web/OmegaLeo.HelperLib.Web.csproj index d794c36..1bd4652 100644 --- a/OmegaLeo.HelperLib.Web/OmegaLeo.HelperLib.Web.csproj +++ b/OmegaLeo.HelperLib.Web/OmegaLeo.HelperLib.Web.csproj @@ -15,7 +15,8 @@ - + + diff --git a/OmegaLeo.HelperLib.Web/Views/Home/Library.cshtml b/OmegaLeo.HelperLib.Web/Views/Home/Library.cshtml index 7666072..8e5d3b8 100644 --- a/OmegaLeo.HelperLib.Web/Views/Home/Library.cshtml +++ b/OmegaLeo.HelperLib.Web/Views/Home/Library.cshtml @@ -1,8 +1,16 @@ @* File: `OmegaLeo.HelperLib.Web/Views/Home/Library.cshtml` *@ +@using ColorCode.Styling +@using GameDevLibrary.Extensions +@using Markdig @model OmegaLeo.HelperLib.Web.Models.LibraryDocumentationViewModel @{ ViewData["Title"] = Model.LibraryName; var groupedByNamespace = Model.Documentation.GroupBy(d => d.AssemblyName).OrderBy(g => g.Key); + + var pipeline = new MarkdownPipelineBuilder() + .UseAdvancedExtensions() + .UseSyntaxHighlighting(StyleDictionary.DefaultDark) + .Build(); }
@@ -75,7 +83,14 @@ { @desc.Title - @Html.Raw(desc.Description) + @Html.Raw(desc.Description)
+ @if (desc.CodeExample.IsNotNullOrEmpty()) + { + Example:
+
+ @Html.Raw(Markdig.Markdown.ToHtml(desc.CodeExample, pipeline)) +
+ } } diff --git a/OmegaLeo.HelperLib.Web/Views/Shared/_Layout.cshtml b/OmegaLeo.HelperLib.Web/Views/Shared/_Layout.cshtml index d2eff25..3e42232 100644 --- a/OmegaLeo.HelperLib.Web/Views/Shared/_Layout.cshtml +++ b/OmegaLeo.HelperLib.Web/Views/Shared/_Layout.cshtml @@ -34,6 +34,14 @@ Game Dev + +
@@ -42,12 +50,6 @@ @RenderBody() -
-
- © @DateTime.Now.Year - OmegaLeo Helper Libraries -
-
- diff --git a/OmegaLeo.HelperLib.Web/wwwroot/css/site.css b/OmegaLeo.HelperLib.Web/wwwroot/css/site.css index f8d98fc..9001678 100644 --- a/OmegaLeo.HelperLib.Web/wwwroot/css/site.css +++ b/OmegaLeo.HelperLib.Web/wwwroot/css/site.css @@ -19,4 +19,22 @@ html { body { margin-bottom: 60px; +} + +pre { + overflow: auto; + padding: 1rem; + background-color: #495057; + position: relative; + + color: #f2f2f2; +} + +code { + background-color: transparent !important; +} + +.example-code > div { + border-radius: 0.5rem !important; + background-color: #495057 !important; } \ No newline at end of file diff --git a/OmegaLeo.HelperLib.sln.DotSettings.user b/OmegaLeo.HelperLib.sln.DotSettings.user index fd5e489..b792ae4 100644 --- a/OmegaLeo.HelperLib.sln.DotSettings.user +++ b/OmegaLeo.HelperLib.sln.DotSettings.user @@ -1,4 +1,5 @@  + ForceIncluded ForceIncluded ForceIncluded ForceIncluded diff --git a/OmegaLeo.HelperLib/Helpers/BenchmarkUtility.cs b/OmegaLeo.HelperLib/Helpers/BenchmarkUtility.cs index 6b2a1ff..1e33fe5 100644 --- a/OmegaLeo.HelperLib/Helpers/BenchmarkUtility.cs +++ b/OmegaLeo.HelperLib/Helpers/BenchmarkUtility.cs @@ -1,14 +1,22 @@ using System; using System.Collections.Generic; using System.Diagnostics; +using NetFlow.DocumentationHelper.Library.Attributes; namespace GameDevLibrary.Helpers { + [Documentation(nameof(BenchmarkUtility), "Utility class for benchmarking code execution time.", null, @"```csharp +BenchmarkUtility.Start(""MyBenchmark""); +// Code to benchmark +BenchmarkUtility.Stop(""MyBenchmark""); +var results = BenchmarkUtility.GetResults(""MyBenchmark""); +```")] public class BenchmarkUtility { private static Dictionary> _benchmarks = new Dictionary>(); private static Dictionary _stopwatches = new Dictionary(); + [Documentation("GetStopwatch", "Retrieves or creates a Stopwatch instance for the given key.", null, null)] private static Stopwatch GetStopwatch(string key) { Stopwatch stopwatch; @@ -22,6 +30,14 @@ namespace GameDevLibrary.Helpers return stopwatch; } + [Documentation("Record", "Records the execution time of the provided action and returns the elapsed time in milliseconds.", null, @"```csharp +var time = BenchmarkUtility.Record(() => +{ + // Code to benchmark +}); + +Console.WriteLine($""Elapsed time: {time} ms""); +```")] public static long Record(Action actionToRecord) { var stopwatch = new Stopwatch(); @@ -33,6 +49,19 @@ namespace GameDevLibrary.Helpers return stopwatch.ElapsedMilliseconds; } + [Documentation("RecordAndSaveToResults", "Records the execution time of the provided action, saves it under the given key, and returns the elapsed time in milliseconds.", null, @"```csharp +var time = BenchmarkUtility.RecordAndSaveToResults(""MyBenchmark"", () => +{ + // Code to benchmark +}); + +Console.WriteLine($""Elapsed time: {time} ms""); + +var results = BenchmarkUtility.GetResults(""MyBenchmark""); + +var averageTime = results.Average(); +Console.WriteLine($""Average time: {averageTime} ms""); +```")] public static long RecordAndSaveToResults(string key, Action actionToRecord) { var stopwatch = new Stopwatch(); @@ -52,11 +81,13 @@ namespace GameDevLibrary.Helpers return stopwatch.ElapsedMilliseconds; } + [Documentation("Start", "Starts or restarts the stopwatch for the given key.", null, null)] public static void Start(string key) { GetStopwatch(key).Restart(); } + [Documentation("Stop", "Stops the stopwatch for the given key and records the elapsed time.", null, null)] public static void Stop(string key) { if (!_benchmarks.ContainsKey(key)) @@ -68,16 +99,19 @@ namespace GameDevLibrary.Helpers _benchmarks[key].Add(GetStopwatch(key).ElapsedMilliseconds); } + [Documentation("GetResults", "Retrieves the list of recorded times for the given key.", null, null)] public static List GetResults(string key) { return _benchmarks.ContainsKey(key) ? _benchmarks[key] : new List(); } + [Documentation("ClearResults", "Clears all recorded benchmark results.", null, null)] public static void ClearResults() { _benchmarks.Clear(); } + [Documentation("GetAllResults", "Retrieves all recorded benchmark results.", null, null)] public static Dictionary> GetAllResults() { return new Dictionary>(_benchmarks); diff --git a/OmegaLeo.HelperLib/OmegaLeo.HelperLib.csproj b/OmegaLeo.HelperLib/OmegaLeo.HelperLib.csproj index 52f6963..d9f20ce 100644 --- a/OmegaLeo.HelperLib/OmegaLeo.HelperLib.csproj +++ b/OmegaLeo.HelperLib/OmegaLeo.HelperLib.csproj @@ -14,7 +14,7 @@ - +