Document ValueWriter, add basic OpaqueValue handling

Signed-off-by: Nicholas Van Sickle <nvsickle@amazon.com>

Code/Framework/AzCore/AzCore/DOM/DomValueWriter.cpp

@@ -220,6 +220,12 @@ namespace AZ::Dom
         return EndContainer(Type::Node, attributeCount, elementCount);
     }
 
+    Visitor::Result ValueWriter::OpaqueValue(OpaqueType& value)
+    {
+        CurrentValue().SetOpaqueValue(value);
+        return FinishWrite();
+    }
+
     Visitor::Result ValueWriter::FinishWrite()
     {
         if (m_entryStack.empty())

Code/Framework/AzCore/AzCore/DOM/DomValueWriter.h

@@ -13,6 +13,8 @@
 
 namespace AZ::Dom
 {
+    //! Visitor that writes to a Value.
+    //! Supports all Visitor operations.
     class ValueWriter : public Visitor
     {
     public:
@@ -36,6 +38,7 @@ namespace AZ::Dom
         Result StartNode(AZ::Name name) override;
         Result RawStartNode(AZStd::string_view name, Lifetime lifetime) override;
         Result EndNode(AZ::u64 attributeCount, AZ::u64 elementCount) override;
+        Result OpaqueValue(OpaqueType& value) override;
 
     private:
         Result FinishWrite();
@@ -60,7 +63,10 @@ namespace AZ::Dom
         ValueBuffer& GetValueBuffer();
 
         Value& m_result;
+        // Stores info about the current value being processed
         AZStd::stack<ValueInfo> m_entryStack;
+        // Provides temporary storage for elements and attributes to prevent extra heap allocations
+        // These buffers persist to be reused even as the entry stack changes
         AZStd::vector<ValueBuffer> m_valueBuffers;
     };
 } // namespace AZ::Dom

Code/Framework/AzCore/AzCore/DOM/DomVisitor.cpp

@@ -110,7 +110,7 @@ namespace AZ::Dom
         return String(*value, lifetime);
     }
 
-    Visitor::Result Visitor::OpaqueValue([[maybe_unused]] const OpaqueType& value, [[maybe_unused]] Lifetime lifetime)
+    Visitor::Result Visitor::OpaqueValue([[maybe_unused]] OpaqueType& value)
     {
         if (!SupportsOpaqueValues())
         {

Code/Framework/AzCore/AzCore/DOM/DomVisitor.h

@@ -181,8 +181,7 @@ namespace AZ::Dom
         //! indicate where the value may be stored persistently or requires a copy.
         //! The base implementation of OpaqueValue rejects the operation, as opaque values are meant for special
         //! cases with specific implementations, not generic usage.
-        //! Storage semantics are provided to indicate where the value may be stored persistently or requires a copy.
-        virtual Result OpaqueValue(const OpaqueType& value, Lifetime lifetime);
+        virtual Result OpaqueValue(OpaqueType& value);
         //! Operates on a raw value encoded as a UTF-8 string that hasn't had its type deduced.
         //! Visitors that support raw values (\see VisitorFlags::SupportsRawValues) may parse the raw value and
         //! forward it to the corresponding value call or calls of their choice.