Docs: update with rfl::Deprecated (#625)

Author: AndrewNolte

README.md

@@ -367,6 +367,7 @@ struct Person {
       std::vector<Person>>
       children;
   float salary;
+  rfl::Deprecated<"Use Salary Instead", "Wage in dollars", std::optional<int>> wage;
 };
 
 const std::string json_schema = rfl::json::to_schema<Person>();
@@ -375,7 +376,7 @@ const std::string json_schema = rfl::json::to_schema<Person>();
 The resulting JSON schema looks like this:
 
 ```json
-{"$schema":"https://json-schema.org/draft/2020-12/schema","$ref":"#/$defs/Person","$defs":{"Person":{"type":"object","properties":{"children":{"type":"array","description":"The person's children. Pass an empty array for no children.","items":{"$ref":"#/$defs/Person"}},"email":{"type":"string","description":"Must be a proper email in the form xxx@xxx.xxx.","pattern":"^[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$"},"first_name":{"type":"string"},"last_name":{"type":"string"},"salary":{"type":"number"}},"required":["children","email","first_name","last_name","salary"]}}}
+{"$schema":"https://json-schema.org/draft/2020-12/schema","$ref":"#/$defs/Person","$defs":{"Person":{"type":"object","properties":{"children":{"type":"array","description":"The person's children. Pass an empty array for no children.","items":{"$ref":"#/$defs/Person"}},"email":{"type":"string","description":"Must be a proper email in the form xxx@xxx.xxx.","pattern":"^[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}$"},"first_name":{"type":"string"},"last_name":{"type":"string"},"salary":{"type":"number"},"wage":{"type":"integer","description":"Wage in dollars","deprecated":true,"deprecationMessage":"Use Salary Instead"}},"required":["children","email","first_name","last_name","salary"]}}}
 ```
 
 Note that this is currently supported for JSON only, since most other formats do not support schemata in the first place.

docs/json_schema.md

@@ -192,3 +192,55 @@ const std::string json_schema = rfl::json::to_schema<
     }
 }
 ```
+
+## Indicating deprecated fields
+
+You can mark fields as deprecated in the JSON schema using `rfl::Deprecated`. This adds `"deprecated": true` and a `"deprecationMessage"` to the generated schema, along with a description.
+
+`rfl::Deprecated` takes three template parameters: a deprecation message, a description, and the underlying type:
+
+```cpp
+struct Person {
+  rfl::Deprecated<"Use 'full_name' instead.", "The person's first name", std::optional<std::string>>
+      std::optional<first_name>;
+  rfl::Description<"The person's full name", std::string> full_name;
+  float salary;
+};
+```
+
+```cpp
+const std::string json_schema = rfl::json::to_schema<Person>(rfl::json::pretty);
+```
+
+```json
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$ref": "#/$defs/Person",
+    "$defs": {
+        "Person": {
+            "type": "object",
+            "properties": {
+                "first_name": {
+                    "type": "string",
+                    "description": "The person's first name",
+                    "deprecated": true,
+                    "deprecationMessage": "Use 'full_name' instead."
+                },
+                "full_name": {
+                    "type": "string",
+                    "description": "The person's full name"
+                },
+                "salary": {
+                    "type": "number"
+                }
+            },
+            "required": [
+                "full_name",
+                "salary"
+            ]
+        }
+    }
+}
+```
+
+`rfl::Deprecated` behaves like a thin wrapper around the underlying type, just like `rfl::Description`. You can access the underlying value using `.get()`, `.value()`, `operator()()`, or the assignment operator.