From ce3bc470ba1efc53db04ebeb162171a49dac7ab5 Mon Sep 17 00:00:00 2001
From: Antoine Stevan <44101798+amtoine@users.noreply.github.com>
Date: Sun, 5 May 2024 15:34:22 +0200
Subject: [PATCH] improve NUON documentation (#12717)

# Description
this PR
- moves the documentation from `lib.rs` to `README.md` while still
including it in the lib file, so that both the [crates.io
page](https://crates.io/crates/nuon) and the
[documentation](https://docs.rs/nuon/latest/nuon/) show the top-level
doc
- mention that comments are allowed in NUON
- add a JSON-NUON example
- put back the formatting of NOTE blocks in the doc

# User-Facing Changes

# Tests + Formatting

# After Submitting
---
 crates/nuon/README.md   | 35 +++++++++++++++++++++++++++++++++++
 crates/nuon/src/from.rs |  4 +++-
 crates/nuon/src/lib.rs  |  7 +------
 crates/nuon/src/to.rs   |  4 +++-
 4 files changed, 42 insertions(+), 8 deletions(-)
 create mode 100644 crates/nuon/README.md

diff --git a/crates/nuon/README.md b/crates/nuon/README.md
new file mode 100644
index 0000000000..d11aa8104c
--- /dev/null
+++ b/crates/nuon/README.md
@@ -0,0 +1,35 @@
+Support for the NUON format.
+
+The NUON format is a superset of JSON designed to fit the feel of Nushell.
+Some of its extra features are
+- trailing commas are allowed
+- commas are optional in lists
+- quotes are not required around keys or any _bare_ string that do not contain spaces
+- comments are allowed, though not preserved when using [`from_nuon`]
+
+## Example
+below is some data in the JSON format
+```json
+{
+    "name": "Some One",
+    "birth": "1970-01-01",
+    "stats": [
+      2544729499973429198,
+      687051042647753531,
+      6702443901704799912
+    ]
+}
+```
+
+and an equivalent piece of data written in NUON
+```nuon
+{
+    name: "Some One",       # the name of the person
+    birth: "1970-01-01",    # their date of birth
+    stats: [                # some dummy "stats" about them
+      2544729499973429198,
+      687051042647753531,
+      6702443901704799912, # note the trailing comma here...
+    ], # and here
+} # wait, are these comments in a JSON-like document?!?!
+```
diff --git a/crates/nuon/src/from.rs b/crates/nuon/src/from.rs
index 457b12d5f9..862b756db7 100644
--- a/crates/nuon/src/from.rs
+++ b/crates/nuon/src/from.rs
@@ -7,7 +7,9 @@ use std::sync::Arc;
 
 /// convert a raw string representation of NUON data to an actual Nushell [`Value`]
 ///
-/// > **Note**
+// WARNING: please leave the following two trailing spaces, they matter for the documentation
+// formatting
+/// > **Note**  
 /// > [`Span`] can be passed to [`from_nuon`] if there is context available to the caller, e.g. when
 /// > using this function in a command implementation such as
 /// [`from nuon`](https://www.nushell.sh/commands/docs/from_nuon.html).
diff --git a/crates/nuon/src/lib.rs b/crates/nuon/src/lib.rs
index cb86480580..891ccae62a 100644
--- a/crates/nuon/src/lib.rs
+++ b/crates/nuon/src/lib.rs
@@ -1,9 +1,4 @@
-//! Support for the NUON format.
-//!
-//! The NUON format is a superset of JSON designed to fit the feel of Nushell.
-//! Some of its extra features are
-//! - trailing commas are allowed
-//! - quotes are not required around keys
+#![doc = include_str!("../README.md")]
 mod from;
 mod to;
 
diff --git a/crates/nuon/src/to.rs b/crates/nuon/src/to.rs
index 30fe2664a2..8aeb47a097 100644
--- a/crates/nuon/src/to.rs
+++ b/crates/nuon/src/to.rs
@@ -39,7 +39,9 @@ pub enum ToStyle {
 
 /// convert an actual Nushell [`Value`] to a raw string representation of the NUON data
 ///
-/// > **Note**
+// WARNING: please leave the following two trailing spaces, they matter for the documentation
+// formatting
+/// > **Note**  
 /// > a [`Span`] can be passed to [`to_nuon`] if there is context available to the caller, e.g. when
 /// > using this function in a command implementation such as [`to nuon`](https://www.nushell.sh/commands/docs/to_nuon.html).
 ///