Merge in master to bring branch up to date

crozone · Aug 25, 2020 · 4f9a904 · 4f9a904
2 parents 6353d9f + fb8e3c2
commit 4f9a904
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 47 deletions.
diff --git a/FormatWith/FormatWith.csproj b/FormatWith/FormatWith.csproj
@@ -1,41 +1,41 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-  <PropertyGroup>
-    <TargetFramework>netstandard2.0</TargetFramework>
-    <Title>FormatWith</Title>
-    <Product>FormatWith</Product>
-    <Description>String extension methods for performing {named} {{parameterized}} string formatting, written for NetStandard 2.0</Description>
-    <AssemblyName>FormatWith</AssemblyName>
-    <AssemblyTitle>FormatWith</AssemblyTitle>
-    <PackageId>FormatWith</PackageId>
-    <VersionPrefix>3.0.0</VersionPrefix>
-    <Authors>Ryan Crosby</Authors>
-    <Copyright>Copyright © Ryan Crosby 2017 - 2020</Copyright>
-    <PackageTags>named string formatter extension NetStandard 2.0</PackageTags>
-    <PackageProjectUrl>https://github.com/crozone/FormatWith</PackageProjectUrl>
-    <PackageLicenseUrl>https://opensource.org/licenses/MIT</PackageLicenseUrl>
-    <PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
-    <GenerateAssemblyTitleAttribute>false</GenerateAssemblyTitleAttribute>
-    <GenerateAssemblyDescriptionAttribute>false</GenerateAssemblyDescriptionAttribute>
-    <GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
-    <GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
-    <GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
-    <GenerateAssemblyCopyrightAttribute>false</GenerateAssemblyCopyrightAttribute>
-    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
-    <RepositoryUrl>https://github.com/crozone/FormatWith</RepositoryUrl>
-    <RepositoryType>git</RepositoryType>
-    <PackageReleaseNotes>Key:format syntax now supported for FormatWith and FormattableWith</PackageReleaseNotes>
-    <SignAssembly>true</SignAssembly>
-    <AssemblyOriginatorKeyFile>FormatWith-Release.snk</AssemblyOriginatorKeyFile>
-    <DelaySign>false</DelaySign>
-  </PropertyGroup>
+	<PropertyGroup>
+		<TargetFramework>netstandard2.0</TargetFramework>
+		<Title>FormatWith</Title>
+		<Product>FormatWith</Product>
+		<Description>String extension methods for performing {named} {{parameterized}} string formatting, written for NetStandard 2.0</Description>
+		<AssemblyName>FormatWith</AssemblyName>
+		<AssemblyTitle>FormatWith</AssemblyTitle>
+		<PackageId>FormatWith</PackageId>
+		<VersionPrefix>3.0.0</VersionPrefix>
+		<Authors>Ryan Crosby</Authors>
+		<Copyright>Copyright © Ryan Crosby 2017 - 2020</Copyright>
+		<PackageTags>named string formatter extension NetStandard 2.0</PackageTags>
+		<PackageProjectUrl>https://github.com/crozone/FormatWith</PackageProjectUrl>
+		<PackageLicenseExpression>MIT</PackageLicenseExpression>
+		<PackageRequireLicenseAcceptance>true</PackageRequireLicenseAcceptance>
+		<GenerateAssemblyTitleAttribute>false</GenerateAssemblyTitleAttribute>
+		<GenerateAssemblyDescriptionAttribute>false</GenerateAssemblyDescriptionAttribute>
+		<GenerateAssemblyConfigurationAttribute>false</GenerateAssemblyConfigurationAttribute>
+		<GenerateAssemblyCompanyAttribute>false</GenerateAssemblyCompanyAttribute>
+		<GenerateAssemblyProductAttribute>false</GenerateAssemblyProductAttribute>
+		<GenerateAssemblyCopyrightAttribute>false</GenerateAssemblyCopyrightAttribute>
+		<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
+		<RepositoryUrl>https://github.com/crozone/FormatWith</RepositoryUrl>
+		<RepositoryType>git</RepositoryType>
+		<PackageReleaseNotes>Key:format syntax now supported for FormatWith and FormattableWith</PackageReleaseNotes>
+		<SignAssembly>true</SignAssembly>
+		<AssemblyOriginatorKeyFile>FormatWith-Release.snk</AssemblyOriginatorKeyFile>
+		<DelaySign>false</DelaySign>
+	</PropertyGroup>
 
-  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
-    <DocumentationFile>bin\Debug\netstandard2.0\FormatWith.xml</DocumentationFile>
-  </PropertyGroup>
-  
-  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
-    <DocumentationFile>bin\Release\netstandard2.0\FormatWith.xml</DocumentationFile>
-  </PropertyGroup>
+	<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
+		<DocumentationFile>bin\Debug\netstandard2.0\FormatWith.xml</DocumentationFile>
+	</PropertyGroup>
+
+	<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
+		<DocumentationFile>bin\Release\netstandard2.0\FormatWith.xml</DocumentationFile>
+	</PropertyGroup>
 
 </Project>
diff --git a/FormatWith/Internal/FormatHelpers.cs b/FormatWith/Internal/FormatHelpers.cs
@@ -11,15 +11,16 @@ namespace FormatWith.Internal
     /// </summary>
     internal static class FormatHelpers
     {
-            /// <summary>
-            /// Processes a list of format tokens into a string
-            /// </summary>
-            /// <param name="tokens">List of tokens to turn into a string</param>
-            /// <param name="replacements">An <see cref="IDictionary"/> with keys and values to inject into the formatted result</param>
-            /// <param name="missingKeyBehaviour">The behaviour to use when the format string contains a parameter that is not present in the lookup dictionary</param>
-            /// <param name="fallbackReplacementValue">When the <see cref="MissingKeyBehaviour.ReplaceWithFallback"/> is specified, this string is used as a fallback replacement value when the parameter is present in the lookup dictionary.</param>
-            /// <returns>The processed result of joining the tokens with the replacement dictionary.</returns>
-            public static string ProcessTokens(
+        /// <summary>
+        /// Processes a list of format tokens into a string
+        /// </summary>
+        /// <param name="tokens">List of tokens to turn into a string</param>
+        /// <param name="handler">The function used to perform the replacements on the format tokens</param>
+        /// <param name="missingKeyBehaviour">The behaviour to use when the format string contains a parameter that is not present in the lookup dictionary</param>
+        /// <param name="fallbackReplacementValue">When the <see cref="MissingKeyBehaviour.ReplaceWithFallback"/> is specified, this string is used as a fallback replacement value when the parameter is present in the lookup dictionary.</param>
+        /// <param name="outputLengthHint">Provides a hint to the underlying string builder to help reduce buffer reallocations.</param>
+        /// <returns>The processed result of joining the tokens with the replacement dictionary.</returns>
+        public static string ProcessTokens(
             IEnumerable<FormatToken> tokens,
             Func<string, string, ReplacementResult> handler,
             MissingKeyBehaviour missingKeyBehaviour,
@@ -97,9 +98,10 @@ public static string ProcessTokens(
         /// Processes a list of format tokens into a string
         /// </summary>
         /// <param name="tokens">List of tokens to turn into a string</param>
-        /// <param name="replacements">An <see cref="IDictionary"/> with keys and values to inject into the formatted result</param>
+        /// <param name="handler">The function used to perform the replacements on the format tokens</param>
         /// <param name="missingKeyBehaviour">The behaviour to use when the format string contains a parameter that is not present in the lookup dictionary</param>
         /// <param name="fallbackReplacementValue">When the <see cref="MissingKeyBehaviour.ReplaceWithFallback"/> is specified, this string is used as a fallback replacement value when the parameter is present in the lookup dictionary.</param>
+        /// <param name="outputLengthHint"></param>
         /// <returns>The processed result of joining the tokens with the replacement dictionary.</returns>
         public static FormattableString ProcessTokensIntoFormattableString(
             IEnumerable<FormatToken> tokens,

diff --git a/FormatWith/Internal/FormatWithMethods.cs b/FormatWith/Internal/FormatWithMethods.cs
@@ -142,7 +142,7 @@ public static FormattableString FormattableWith(
         }
 
         /// <summary>
-        /// Gets an <see cref="IEnumerable{string}"/> that will return all format parameters used within the format string.
+        /// Gets an <see cref="IEnumerable{String}">IEnumerable&lt;string&gt;</see> that will return all format parameters used within the format string.
         /// </summary>
         /// <param name="formatString">The format string to be parsed</param>
         /// <param name="openBraceChar">The character used to begin parameters</param>

diff --git a/FormatWith/ReplacementResult.cs b/FormatWith/ReplacementResult.cs
@@ -4,15 +4,33 @@
 
 namespace FormatWith
 {
+    /// <summary>
+    /// Represents the result of a substitution for a parameter within a format string.
+    /// </summary>
     public struct ReplacementResult
     {
+        /// <summary>
+        /// Represents the result of a substitution for a parameter within a format string.
+        /// </summary>
+        /// <param name="success">Represents whether or not the substitution was successful.</param>
+        /// <param name="value">The new value for the substituted format parameter.</param>
         public ReplacementResult(bool success, object value)
         {
             Success = success;
             Value = value;
         }
 
+        /// <summary>
+        /// Represents whether or not the substitution was successful.
+        /// If true, the handler was successfully able to replace this parameter with the substituted value.
+        /// If false, the substitution failed, and Value will be set to null.
+        /// </summary>
         public bool Success { get; }
+
+        /// <summary>
+        /// The new value for the substituted format parameter.
+        /// If Success is false, this should be set to null.
+        /// </summary>
         public object Value { get; }
     }
 }