From 20e2ee7ded7881659fd29143167b93925f16543d Mon Sep 17 00:00:00 2001
From: Matt Chaulklin <85208563+MattFromRVA@users.noreply.github.com>
Date: Sat, 20 Jul 2024 03:40:01 -0400
Subject: [PATCH] Docs for SummaryStyle (#2510)

* Added SummaryStyle doc and sample

* Fixed link to source code

* correct spelling
---
 docs/articles/samples/IntroSummaryStyle.md    | 51 +++++++++++++++++++
 .../IntroSummaryStyle.cs                      | 39 ++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 docs/articles/samples/IntroSummaryStyle.md
 create mode 100644 samples/BenchmarkDotNet.Samples/IntroSummaryStyle.cs

diff --git a/docs/articles/samples/IntroSummaryStyle.md b/docs/articles/samples/IntroSummaryStyle.md
new file mode 100644
index 0000000000..470bb901a1
--- /dev/null
+++ b/docs/articles/samples/IntroSummaryStyle.md
@@ -0,0 +1,51 @@
+---
+uid: BenchmarkDotNet.SummaryStyle
+---
+
+## SummaryStyle in BenchmarkDotNet
+
+`SummaryStyle` is a class in BenchmarkDotNet that allows customization of the summary reports of benchmark results. It offers several properties to fine-tune how the results are displayed.
+
+### Usage
+
+You can customize the summary report by specifying various properties of `SummaryStyle`. These properties include formatting options like whether to print units in the header or content, setting the maximum width for parameter columns, and choosing units for size and time measurements.
+
+### Source Code
+
+[!code-csharp[IntroSummaryStyle.cs](../../../samples/BenchmarkDotNet.Samples/IntroSummaryStyle.cs)]
+
+### Properties
+
+- `PrintUnitsInHeader`: Boolean to indicate if units should be printed in the header.
+- `PrintUnitsInContent`: Boolean to control unit printing in the content.
+- `PrintZeroValuesInContent`: Determines if zero values should be printed.
+- `MaxParameterColumnWidth`: Integer defining the max width for parameter columns.
+- `SizeUnit`: Optional `SizeUnit` to specify the unit for size measurements.
+- `TimeUnit`: Optional `TimeUnit` for time measurement units.
+- `CultureInfo`: `CultureInfo` to define culture-specific formatting.
+
+### Example Output
+
+Using SummaryStyle options:
+
+```markdown
+| Method | N   | Mean [ns]     | Error [ns] | StdDev [ns] |
+|------- |---- |--------------:|-----------:|------------:|
+| Sleep  | 10  |  15,644,973.1 |   32,808.7 |    30,689.3 |
+| Sleep  | 100 | 109,440,686.7 |  236,673.8 |   221,384.8 |
+```
+
+Default:
+
+```markdown
+| Method | N   | Mean      | Error    | StdDev   |
+|------- |---- |----------:|---------:|---------:|
+| Sleep  | 10  |  15.65 ms | 0.039 ms | 0.034 ms |
+| Sleep  | 100 | 109.20 ms | 0.442 ms | 0.392 ms |
+```
+
+### Links
+
+* @docs.SummaryStyle
+* The permanent link to this sample: @BenchmarkDotNet.Samples.IntroSummaryStyle
+
diff --git a/samples/BenchmarkDotNet.Samples/IntroSummaryStyle.cs b/samples/BenchmarkDotNet.Samples/IntroSummaryStyle.cs
new file mode 100644
index 0000000000..e24fda60e4
--- /dev/null
+++ b/samples/BenchmarkDotNet.Samples/IntroSummaryStyle.cs
@@ -0,0 +1,39 @@
+using System.Globalization;
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Configs;
+using BenchmarkDotNet.Reports;
+using BenchmarkDotNet.Columns;
+using Perfolizer.Horology;
+
+namespace BenchmarkDotNet.Samples
+{
+    [Config(typeof(Config))]
+    public class IntroSummaryStyle
+    {
+        private class Config : ManualConfig
+        {
+            public Config()
+            {
+                // Configure the summary style here
+                var summaryStyle = new SummaryStyle
+                (
+                    cultureInfo: CultureInfo.InvariantCulture,
+                    printUnitsInHeader: true,
+                    printUnitsInContent: false,
+                    sizeUnit: SizeUnit.KB,
+                    timeUnit: TimeUnit.Nanosecond,
+                    maxParameterColumnWidth: 20
+
+                );
+
+                WithSummaryStyle(summaryStyle);
+            }
+        }
+
+        [Params(10, 100)]
+        public int N;
+
+        [Benchmark]
+        public void Sleep() => System.Threading.Thread.Sleep(N);
+    }
+}
\ No newline at end of file