From 37120cdcd90b79d5dbdf168354d9d4db27058fab Mon Sep 17 00:00:00 2001
From: Illia Larka <larkailya@gmail.com>
Date: Mon, 9 Oct 2023 10:56:12 +0200
Subject: [PATCH] System.Formats.Cbor package's readme (#93021)

* Remove conceptual docummentation item

Removed since is not applicable

* List types library provides

Add list of types which library provides. Listed
public types, means exposed types.

* Add description and usage examples

Add library description. Add few code examples
showing basic functionality for CBOR wirter and reader
types.

* Add related packages section

Since different targets have different dependencies
so I have divided for each section.

* Improve short description

Add 'format' word after abbreviation to have an object
in sentence.

* Remove related packages section

Since there are no related packages.

* Improve array reading/writing example
---
 .../System.Formats.Cbor/src/PACKAGE.md        | 77 +++++++++++++++----
 1 file changed, 64 insertions(+), 13 deletions(-)

diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md
index 96474955ed1b1..ff26f0debbdc0 100644
--- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md
+++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md
@@ -2,40 +2,91 @@
 
 <!-- A description of the package and where one can find more documentation -->
 
+Provides support for reading and writing values in Concise Binary Object Representation (CBOR) format, as originally defined in [IETF RFC 7049](https://www.ietf.org/rfc/rfc7049.html).
 
 
 ## Key Features
 
 <!-- The key features of this package -->
 
-*
-*
-*
+* Reader and writer types for the CBOR format.
+* Built-in support for different CBOR conformance modes.
 
 ## How to Use
 
 <!-- A compelling example on how to use this package with code, as well as any specific guidelines for when to use the package -->
 
+Write and read primitives:
+
+```csharp
+using System.Formats.Cbor;
+
+var cborWriter = new CborWriter(CborConformanceMode.Lax);
+cborWriter.WriteTextString("Hello World");
+
+var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax);
+Console.WriteLine(cborReader.ReadTextString());
+// Hello World
+```
+
+Write and read an array:
+
+```csharp
+var cborWriter = new CborWriter(CborConformanceMode.Lax);
+cborWriter.WriteStartArray(5);
+for (var index = 0; index < 5; index++)
+{
+    cborWriter.WriteInt32(index);
+}
+cborWriter.WriteEndArray();
+
+var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax);
+var arrayLength = cborReader.ReadStartArray();
+for (var index = 0; index < arrayLength; index++)
+{
+    Console.Write(cborReader.ReadInt32());
+}
+// 01234
+cborReader.ReadEndArray();
+```
+
+Inspect writer and reader state:
+
+```csharp
+var cborWriter = new CborWriter(CborConformanceMode.Lax);
+cborWriter.WriteTextString("SomeArray");
+Console.WriteLine(cborWriter.BytesWritten);
+// 10
+Console.WriteLine(cborWriter.IsWriteCompleted);
+// True
+
+var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax);
+Console.WriteLine(cborReader.BytesRemaining);
+// 10
+Console.WriteLine(cborReader.ReadTextString());
+// SomeArray
+Console.WriteLine(cborReader.BytesRemaining);
+// 0
+```
+
 ## Main Types
 
 <!-- The main types provided in this library -->
 
 The main types provided by this library are:
 
-* ``
-* ``
-* ``
+* `System.Formats.Cbor.CborReader`
+* `System.Formats.Cbor.CborWriter`
+* `System.Formats.Cbor.CborReaderState`
+* `System.Formats.Cbor.CborConformanceMode`
+* `System.Formats.Cbor.CborContentException`
+* `System.Formats.Cbor.CborTag`
 
-## Addtional Documentation
+## Additional Documentation
 
 <!-- Links to further documentation. Remove conceptual documentation if not available for the library. -->
 
-* [Conceptual documentation](https://learn.microsoft.com/en-us/dotnet/standard/serialization/**LIBRARYNAME**/overview)
-* [API documentation](https://learn.microsoft.com/en-us/dotnet/api/**LIBRARYNAME**)
-
-## Related Packages
-
-<!-- The related packages associated with this package -->
+* [API documentation](https://learn.microsoft.com/en-us/dotnet/api/system.formats.cbor)
 
 ## Feedback & Contributing