Added docs for experimental features

Author: akade

Akade.IndexedSet.sln

@@ -36,7 +36,13 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SourceGenerator", "SourceGe
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Akade.IndexedSet.InternalSourceGenerator", "SourceGenerator\Akade.IndexedSet.InternalSourceGenerator\Akade.IndexedSet.InternalSourceGenerator.csproj", "{CAAB99B7-218B-417A-B81A-84F30BAC1B4E}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Akade.IndexedSet.InternalSourceGenerator.Tests", "SourceGenerator\Akade.IndexedSet.InternalSourceGenerator.Tests\Akade.IndexedSet.InternalSourceGenerator.Tests.csproj", "{34BEB19B-028A-4CD1-90EB-1E1A62C04671}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Akade.IndexedSet.InternalSourceGenerator.Tests", "SourceGenerator\Akade.IndexedSet.InternalSourceGenerator.Tests\Akade.IndexedSet.InternalSourceGenerator.Tests.csproj", "{34BEB19B-028A-4CD1-90EB-1E1A62C04671}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{A85AE3BF-0E73-4032-9DE5-0EF9200AA43F}"
+	ProjectSection(SolutionItems) = preProject
+		docs\Benchmarks.md = docs\Benchmarks.md
+		docs\ExperimentalFeatures.md = docs\ExperimentalFeatures.md
+	EndProjectSection
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -86,6 +92,7 @@ Global
 		{71BE73BD-968F-4CA2-A8A1-FF53EB829359} = {7F8BE28E-51E4-4818-B0C9-BDD357CCDAFA}
 		{CAAB99B7-218B-417A-B81A-84F30BAC1B4E} = {601B55BB-32DD-491A-816E-127FC48BCCEA}
 		{34BEB19B-028A-4CD1-90EB-1E1A62C04671} = {601B55BB-32DD-491A-816E-127FC48BCCEA}
+		{A85AE3BF-0E73-4032-9DE5-0EF9200AA43F} = {1D4D9594-0CD1-4103-AA2E-8589FBBD6EAC}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {C65ABA45-764F-4D07-A2A5-800115204611}

README.md

@@ -12,26 +12,8 @@ In a nutshell, it allows you to write LINQ-like queries *without* enumerating th
 through your data, expect huge [speedups](docs/Benchmarks.md) and much better scalability!
 
 <!--TOC-->
-  - [Overview](#overview)
-    - [Design Goals](#design-goals)
-    - [Performance and Operation-Support of the different indices:](#performance-and-operation-support-of-the-different-indices)
-      - [General queries](#general-queries)
-      - [String queries](#string-queries)
-  - [Features](#features)
-    - [Unique index (single entity, single key)](#unique-index-single-entity-single-key)
-    - [Non-unique index (multiple entities, single key)](#non-unique-index-multiple-entities-single-key)
-    - [Non-unique index (multiple entities, multiple keys)](#non-unique-index-multiple-entities-multiple-keys)
-    - [Range index](#range-index)
-    - [String indices and fuzzy matching](#string-indices-and-fuzzy-matching)
-    - [Computed or compound key](#computed-or-compound-key)
-    - [Concurrency and Thread-Safety](#concurrency-and-thread-safety)
-    - [No reflection and no expressions - convention-based index naming](#no-reflection-and-no-expressions-convention-based-index-naming)
-  - [FAQs](#faqs)
-    - [How do I use multiple index types for the same property?](#how-do-i-use-multiple-index-types-for-the-same-property)
-    - [How do I update key values if the elements are already in the set?](#how-do-i-update-key-values-if-the-elements-are-already-in-the-set)
-    - [How do I do case-insensitve (fuzzy) string matching (Prefix, FullTextIndex)?](#how-do-i-do-case-insensitve-fuzzy-string-matching-prefix-fulltextindex)
-  - [Roadmap](#roadmap)
 <!--/TOC-->
+
 ## Overview
 
 A sample showing different queries as you might want do for a report:
@@ -229,9 +211,11 @@ IEnumerable<GraphNode> nodesThatConnectTo3 = set.Where(x => x.ConnectsTo, contai
 nodesThatConnectTo1 = set.FullScan().Where(x => x.ConnectsTo.Contains(1)); // returns nodes 3 & 4, but enumerates through the entire set
 ```
 
-> ⚠ For range queries, this introduces a small overhead as the results are filtered to be distinct: 
+> :information_source: For range queries, this introduces a small overhead as the results are filtered to be distinct: 
 > i.e. `O(log n + m log m)` instead of `O(log n + m)`.
 
+> :information_source: Multi-key string indices are marked experimental. Read more at [Experimental Features](docs/ExperimentalFeatures.md#AkadeIndexedSetEXP0001)
+
 
 ### Computed or compound key
 
@@ -348,6 +332,7 @@ Potential features (not ordered):
 - [x] Benchmarks
 - [x] Simplification of string indices, i.e. Span/String based overloads to avoid `AsMemory()`...
 - [x] Analyzers to help with best practices
+- [x] Multi-key everything: All index types can be used with multiple keys per element.
 - [ ] Tree-based range index for better insertion performance
 - [ ] Aggregates (i.e. sum or average: interface based on state & add/removal state update functions)
 - [ ] Custom (equality) comparators for indices

docs/ExperimentalFeatures.md

@@ -0,0 +1,13 @@
+# Experimental Features
+
+The new (.NET 8.0) [Experimental Attribute](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute) is used to mark features that are more likely to change in the future.
+**They are usually production-ready**, but we want to gather feedback from the community before we finalize them.
+
+> :warning: In .NET 6 & 7, the `ExperimentalAttribute` is not available and we polyfill it but there is no compiler warning / error that will guide you!
+
+## AkadeIndexedSetEXP0001 
+:information_source: **Multi-key string indices**
+
+The multi-key string indices API is considered to be experimental because the API is allocation-heavy and might change to a `Span`-based API in the future.
+
+However, the feature itself is production-ready, supported and is here to stay.