Document Render Core And API

API/RenderResult.cs

@@ -7,6 +7,9 @@ namespace ADOFAIRenderer.API;
 /// <summary>
 /// Represents the result and metadata of a completed or canceled render session.
 /// </summary>
+/// <remarks>
+/// Passed to the completion callback registered with <see cref="RenderSession.OnComplete"/>. Immutable.
+/// </remarks>
 [SuppressMessage("ReSharper", "UnusedType.Global")]
 [SuppressMessage("ReSharper", "MemberCanBePrivate.Global")]
 public class RenderResult
@@ -17,7 +20,10 @@ public class RenderResult
     public bool Success { get; }
 
     /// <summary>
-    /// The absolute output path of the rendered video file. Empty string if rendering failed or output was not created.
+    /// The output path of the rendered video file: the path given to <see cref="RenderSession.WithOutputPath"/> as passed
+    /// (relative if it was relative), or the path of the time-stamped file in the output directory chosen in the mod
+    /// settings (by default &lt;game root&gt;/Render).
+    /// Empty string if rendering failed or was cancelled (the unfinished file is deleted).
     /// </summary>
     public string OutputPath { get; }
 
@@ -27,12 +33,13 @@ public class RenderResult
     public long TotalFrames { get; }
 
     /// <summary>
-    /// The calculated video duration in seconds (based on TotalFrames and FPS).
+    /// The calculated video duration in seconds: <see cref="TotalFrames"/> divided by the effective video frame rate
+    /// (min of the configured VideoFPS and RenderFPS); 0 when the frame rate is not positive.
     /// </summary>
     public double VideoDuration { get; }
 
     /// <summary>
-    /// Total wall-clock time spent rendering.
+    /// Total wall-clock time spent rendering, from the end of the countdown (start of capture) to the end of the render.
     /// </summary>
     public TimeSpan RenderDuration { get; }
 
@@ -43,6 +50,8 @@ public class RenderResult
 
     /// <summary>
     /// Error message or reason if rendering failed or was canceled; <c>null</c> on success.
+    /// A cancelled render has "Rendering was cancelled by user."; a failed render has "Rendering failed: " followed by
+    /// the reason. Use <see cref="Success"/> to test the outcome; the texts are meant for display.
     /// </summary>
     public string? ErrorMessage { get; }
     
@@ -82,6 +91,7 @@ public class RenderResult
     /// <param name="fps">The effective frames per second used to compute video duration.</param>
     /// <param name="renderDuration">Total wall-clock time spent rendering.</param>
     /// <returns>A new <see cref="RenderResult"/> representing a successful render session.</returns>
+    /// <remarks>The file size is read from disk; it is 0 when the file does not exist or cannot be read.</remarks>
     internal static RenderResult CreateSuccess(string outputPath, long totalFrames, double fps, TimeSpan renderDuration)
     {
         var fileSizeBytes = 0L;
@@ -103,6 +113,7 @@ public class RenderResult
     /// <param name="fps">The effective frames per second used to compute video duration.</param>
     /// <param name="renderDuration">Total wall-clock time spent rendering prior to termination.</param>
     /// <returns>A new <see cref="RenderResult"/> representing a failed or canceled render session.</returns>
+    /// <remarks>OutputPath is empty and FileSizeBytes is 0. A null message is replaced by a generic one.</remarks>
     internal static RenderResult CreateFailure(string? errorMessage, long totalFrames, double fps, TimeSpan renderDuration)
     {
         var videoDuration = fps > 0 ? totalFrames / fps : 0.0;