Update documentation

linkdotnet · Apr 4, 2022 · 3d23142 · 3d23142
1 parent 9f6a9e3
commit 3d23142
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -23,6 +23,10 @@ But sometimes low allocation is key. Therefore I created the `ValueStringBuilder
 If you want to know how the `ValueStringBuilder` works and why it uses allocations and is even faster, checkout [this](https://steven-giesel.com/blogPost/4cada9a7-c462-4133-ad7f-e8b671987896) blog post.
 The blog goes a bit more in detail how it works with a simplistic version of the `ValueStringBuilder`.
 
+## What it doesn't solve!
+The library is not meant as a general replacement for the `StringBuilder` shipped with the .net framework itself. You can head over to the documentation and read about the "Known limitations".
+The library works best for a small to medium amount of strings (not multiple 100'000 characters, even though it is still faster and uses less allocations). At anytime you can convert the `ValueStringBuilder` to a "normal" `StringBuilder`. 
+
 ## Benchmark
 The following table gives you a small comparison between the `StringBuilder` which is part of .NET and the `ValueStringBuilder`:
 

diff --git a/docs/site/articles/known_limitations.md b/docs/site/articles/known_limitations.md
@@ -8,4 +8,18 @@ The base of the `ValueStringBuilder` is a `ref struct`. With that there are cert
 
 If not off this applies to your use case, you are good to go. Using `ref struct` is a trade for performance and less allocations in contrast to its use cases.
 
-`ValueStringBuilder` offers the possibility to "convert" it into a "regular" `System.Text.StringBuilder`. Check out the following extension method via the <xref:LinkDotNet.StringBuilder.ValueStringBuilderExtensions>.
+`ValueStringBuilder` offers the possibility to "convert" it into a "regular" `System.Text.StringBuilder`. Check out the following extension method via the <xref:LinkDotNet.StringBuilder.ValueStringBuilderExtensions>.
+
+## Fluent notation
+
+The normal `StringBuilder` offers a fluent way of appending new strings as follows:
+```csharp
+var stringBuilder = new StringBuilder();
+var greeting = stringBuilder
+    .AppendLine("Hello")
+    .AppendLine("World")
+    .Append("Not a new line afterwards")
+    .ToString();
+```
+
+This does not work with the `ValueStringBuilder`. The simple reason: `struct`s can't return `return ref this`. If we don't return the reference then new allocations are introduced and can also lead to potential bugs / issues. Therefore it is a conscious design decision not to allow fluent notation.
diff --git a/docs/site/index.md b/docs/site/index.md
@@ -10,6 +10,8 @@
 The package is hosted on nuget.org, so easily add the package reference:
 > PM> Install-Package LinkDotNet.StringBuilder
 
+Afterwards you can simply use it. It tries to mimic the API of the `StringBuilder` to a certain extend so for simpler cases you can exchange those two.
+
 
 ## Example usage
 The API is leaning towards the normal `StringBuilder` which is part of the .net framework itself. The main key difference is, that the `ValueStringBuilder` does **not** use the fluent notation of its "big brother".