From b403c6da743d618ce61c68e6caf14da65c7b0c5f Mon Sep 17 00:00:00 2001
From: chrysn <chrysn@fsfe.org>
Date: Mon, 13 Jan 2025 16:02:04 +0100
Subject: [PATCH] book: Dokument :cbor hint

---
 book/src/hints.md | 43 ++++++++++++++++++++++++++++++-------------
 1 file changed, 30 insertions(+), 13 deletions(-)

diff --git a/book/src/hints.md b/book/src/hints.md
index 61dd8825..e57ec666 100644
--- a/book/src/hints.md
+++ b/book/src/hints.md
@@ -8,19 +8,20 @@ The hint follows the syntax `:Display` and must come after the type within the b
 
 The following display hints are currently supported:
 
-| hint   | name                                                     |
-| :----- | :------------------------------------------------------- |
-| `:x`   | lowercase hexadecimal                                    |
-| `:X`   | uppercase hexadecimal                                    |
-| `:?`   | `core::fmt::Debug`-like                                  |
-| `:b`   | binary                                                   |
-| `:o`   | octal                                                    |
-| `:a`   | ASCII                                                    |
-| `:ms`  | timestamp in seconds (input in milliseconds)             |
-| `:us`  | timestamp in seconds (input in microseconds)             |
-| `:ts`  | timestamp in human-readable time (input in seconds)      |
-| `:tms` | timestamp in human-readable time (input in milliseconds) |
-| `:tus` | timestamp in human-readable time (input in microseconds) |
+| hint    | name                                                     |
+| :------ | :------------------------------------------------------- |
+| `:x`    | lowercase hexadecimal                                    |
+| `:X`    | uppercase hexadecimal                                    |
+| `:?`    | `core::fmt::Debug`-like                                  |
+| `:b`    | binary                                                   |
+| `:o`    | octal                                                    |
+| `:a`    | ASCII                                                    |
+| `:ms`   | timestamp in seconds (input in milliseconds)             |
+| `:us`   | timestamp in seconds (input in microseconds)             |
+| `:ts`   | timestamp in human-readable time (input in seconds)      |
+| `:tms`  | timestamp in human-readable time (input in milliseconds) |
+| `:tus`  | timestamp in human-readable time (input in microseconds) |
+| `:cbor` | CBOR encoded items rendered in Diagnostic Notation (EDN) |
 
 The first 4 display hints resemble what's supported in `core::fmt`, for example:
 
@@ -44,6 +45,22 @@ let bytes = [104, 101, 255, 108, 108, 111];
 defmt::info!("{=[u8]:a}", bytes); // -> INFO b"he\xffllo"
 ```
 
+The CBOR display hint is useful when CBOR data is in memory, especially before further processing:
+
+``` rust
+# extern crate defmt;
+# fn parse(slice: &[u8]) -> Result<(), ()> {
+#     Ok(())
+# }
+# fn main() -> Result<(), ()> {
+let id_cred = &[0xa1, 0x04, 0x44, 0x6b, 0x69, 0x64, 0x31];
+
+defmt::info!("Peer ID: {=[u8]:cbor}", id_cred); // -> INFO Peer ID: {4: 'kid1'}
+let parsed = parse(id_cred)?;
+# Ok(())
+# }
+```
+
 ## Alternate printing
 
 Adding `#` in front of a binary, octal, and hexadecimal display hints, precedes these numbers with a base indicator.