diff --git a/NAPS2.Sdk/ImportExport/Placeholders.cs b/NAPS2.Sdk/ImportExport/Placeholders.cs
index 995649e85..0a0f5f036 100644
--- a/NAPS2.Sdk/ImportExport/Placeholders.cs
+++ b/NAPS2.Sdk/ImportExport/Placeholders.cs
@@ -6,6 +6,10 @@ using System.Text.RegularExpressions;
namespace NAPS2.ImportExport
{
+ ///
+ /// Class for handling substitution of special values in file paths. For example, "$(YYYY)" can be substituted with the current year.
+ /// Use Placeholders.All for recommended substitutions. Alternatively, you can use Placeholders.Env or Placeholders.None if you prefer.
+ ///
public abstract class Placeholders
{
public const string YEAR_4_DIGITS = "$(YYYY)";
@@ -20,12 +24,30 @@ namespace NAPS2.ImportExport
public const string NUMBER_2_DIGITS = "$(nn)";
public const string NUMBER_1_DIGIT = "$(n)";
+ ///
+ /// Substitutes all the standard placeholders. For example, "$(YYYY)-$(MM)-$(DD) $(hh):$(mm):$(ss)" is substituted with the current date and time. Substitutes environment variables. Handles auto-numbering for multiple files,
+ /// using the numeric placeholders ("$(n)", "$(nn)", "$(nnn)", or "$(nnnn)") if specified; otherwise, the number is appended to the file name.
+ ///
public static DefaultPlaceholders All => new DefaultPlaceholders();
+ ///
+ /// Substitutes environment variables in file names. Not recommended if you may be saving multiple files.
+ ///
public static EnvironmentPlaceholders Env => new EnvironmentPlaceholders();
+ ///
+ /// Does not make any changes to the file name. Not recommended if you may be saving multiple files.
+ ///
public static StubPlaceholders None => new StubPlaceholders();
+ ///
+ /// Performs substitutions on the given file path.
+ ///
+ /// The file path to perform substitutions on.
+ /// Whether to use an auto-incrementing file number to make the file name unique.
+ /// The file number will be at least one bigger than this value.
+ /// The minimum number of digits in the file number. Only has an effect if the path does not contain a numeric placeholder like $(n) or $(nnn).
+ /// The file path with substitutions.
public abstract string Substitute(string filePath, bool incrementIfExists = true, int numberSkip = 0, int autoNumberDigits = 0);
public class StubPlaceholders : Placeholders
@@ -60,6 +82,11 @@ namespace NAPS2.ImportExport
this.dateTimeOverride = dateTimeOverride;
}
+ ///
+ /// Creates a copy of the DefaultPlaceholders object that will use the specified DateTime for date and time substitutions.
+ ///
+ /// The date and time to use.
+ /// The new DefaultPlaceholders object.
public DefaultPlaceholders WithDate(DateTime dateTime) => new DefaultPlaceholders(dateTime);
public override string Substitute(string filePath, bool incrementIfExists = true, int numberSkip = 0, int autoNumberDigits = 0)