From 8605b975dba5eaac004bfc39946a254f311938b9 Mon Sep 17 00:00:00 2001
From: SylvKT <contact@sylv.gay>
Date: Wed, 3 Jan 2024 22:41:58 -0500
Subject: [PATCH] add documentation, improve comments

---
 docs/extensions.md                 | 24 ++++++++++++++++++++++++
 tests/522_explicit_struct_names.rs |  6 +++---
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/extensions.md b/docs/extensions.md
index a8492202..9d07ca62 100644
--- a/docs/extensions.md
+++ b/docs/extensions.md
@@ -114,3 +114,27 @@ With the `unwrap_variant_newtypes` extension, the first structural layer inside
 ```
 
 Note that when the `unwrap_variant_newtypes` extension is enabled, the first layer inside a newtype variant will **always** be unwrapped, i.e. it is no longer possible to write `A(Inner(a: 4, b: true))` or `A((a: 4, b: true))`.
+
+# explicit_struct_names
+This extension requires that all structs have names attached to them. For example, the following deserializes perfectly fine:
+```ron
+Foo(
+    bar: Bar(42),
+)
+```
+
+However, with the `explicit_struct_names` extension enabled, the following will throw an `ExpectedStructName` error:
+```ron
+(
+    bar: Bar(42),
+)
+```
+
+Similarly, the following will throw the same error:
+```ron
+Foo(
+    bar: (42),
+)
+```
+
+Note that if what you are parsing is spread across many files, you would likely use `Options::with_default_extension` to enable `Extensions::EXPLICIT_STRUCT_NAMES` before the parsing stage. This is because prepending `#![enable(explicit_struct_names)]` to the contents of every file you parse would violate DRY (Don't Repeat Yourself).
diff --git a/tests/522_explicit_struct_names.rs b/tests/522_explicit_struct_names.rs
index f0b94730..e8c4eba0 100644
--- a/tests/522_explicit_struct_names.rs
+++ b/tests/522_explicit_struct_names.rs
@@ -18,7 +18,7 @@ fn explicit_struct_names() {
     let options = Options::default()
         .with_default_extension(Extensions::EXPLICIT_STRUCT_NAMES);
 
-    // phase 1
+    // phase 1 (regular structs)
     let content = r#"(
         id: Id(3),
     )"#;
@@ -28,7 +28,7 @@ fn explicit_struct_names() {
         err => panic!("{INCORRECT_ERROR_MESSAGE} \"{err}\""),
     }
 
-    // phase 2
+    // phase 2 (newtype structs)
     let content = r#"Foo(
         id: (3),
     )"#;
@@ -38,6 +38,6 @@ fn explicit_struct_names() {
         err => panic!("{INCORRECT_ERROR_MESSAGE} \"{err}\""),
     }
 
-    // phase 3 (use content from phase 2)
+    // phase 3 (test without this extension)
     let _foo = from_str::<Foo>(content).unwrap();
 }