From be2db5e7a7f914a51fd41ef4c6133ab77454178f Mon Sep 17 00:00:00 2001
From: Stefan Habel <19556655+StefanHabel@users.noreply.github.com>
Date: Mon, 30 Oct 2023 23:52:14 -0700
Subject: [PATCH] More fixes in header files in MaterialXCore. (#1567)

Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com>
---
 source/MaterialXCore/Definition.h | 42 +++++++++++------------
 source/MaterialXCore/Document.h   | 31 ++++++++++++-----
 source/MaterialXCore/Element.h    |  8 ++---
 source/MaterialXCore/Geom.h       |  4 +--
 source/MaterialXCore/Interface.h  | 26 +++++++-------
 source/MaterialXCore/Look.h       | 20 +++++------
 source/MaterialXCore/Node.h       |  4 +--
 source/MaterialXCore/Types.h      |  4 +--
 source/MaterialXCore/Unit.h       | 56 +++++++++++++++----------------
 source/MaterialXCore/Variant.h    |  4 +--
 10 files changed, 106 insertions(+), 93 deletions(-)

diff --git a/source/MaterialXCore/Definition.h b/source/MaterialXCore/Definition.h
index 6d25b78301..075a3a3efb 100644
--- a/source/MaterialXCore/Definition.h
+++ b/source/MaterialXCore/Definition.h
@@ -96,7 +96,7 @@ class MX_CORE_API NodeDef : public InterfaceElement
         setAttribute(NODE_ATTRIBUTE, node);
     }
 
-    /// Return true if the given NodeDef has a node string.
+    /// Return true if this NodeDef has a node string.
     bool hasNodeString() const
     {
         return hasAttribute(NODE_ATTRIBUTE);
@@ -121,7 +121,7 @@ class MX_CORE_API NodeDef : public InterfaceElement
         setAttribute(NODE_GROUP_ATTRIBUTE, category);
     }
 
-    /// Return true if the given NodeDef has a node group.
+    /// Return true if this NodeDef has a node group.
     bool hasNodeGroup() const
     {
         return hasAttribute(NODE_GROUP_ATTRIBUTE);
@@ -207,7 +207,7 @@ class MX_CORE_API Implementation : public InterfaceElement
         setAttribute(FILE_ATTRIBUTE, file);
     }
 
-    /// Return true if the given Implementation has a file string.
+    /// Return true if this Implementation has a file string.
     bool hasFile() const
     {
         return hasAttribute(FILE_ATTRIBUTE);
@@ -229,7 +229,7 @@ class MX_CORE_API Implementation : public InterfaceElement
         setAttribute(FUNCTION_ATTRIBUTE, function);
     }
 
-    /// Return true if the given Implementation has a function string.
+    /// Return true if this Implementation has a function string.
     bool hasFunction() const
     {
         return hasAttribute(FUNCTION_ATTRIBUTE);
@@ -251,7 +251,7 @@ class MX_CORE_API Implementation : public InterfaceElement
         setAttribute(NODE_GRAPH_ATTRIBUTE, nodegraph);
     }
 
-    /// Return true if the given Implementation has a nodegraph string.
+    /// Return true if this Implementation has a nodegraph string.
     bool hasNodeGraph() const
     {
         return hasAttribute(NODE_GRAPH_ATTRIBUTE);
@@ -277,7 +277,7 @@ class MX_CORE_API Implementation : public InterfaceElement
     /// @name Validation
     /// @{
 
-    /// Validate that the given element tree, including all descendants, is
+    /// Validate that this element tree, including all descendants, is
     /// consistent with the MaterialX specification.
     bool validate(string* message = nullptr) const override;
 
@@ -286,7 +286,7 @@ class MX_CORE_API Implementation : public InterfaceElement
     /// @{
 
     /// Return the first declaration of this interface, optionally filtered
-    ///    by the given target name.
+    /// by the given target name.
     ConstInterfaceElementPtr getDeclaration(const string& target = EMPTY_STRING) const override;
 
     /// @}
@@ -318,7 +318,7 @@ class MX_CORE_API TypeDef : public Element
         setAttribute(SEMANTIC_ATTRIBUTE, semantic);
     }
 
-    /// Return true if the given TypeDef has a semantic string.
+    /// Return true if this TypeDef has a semantic string.
     bool hasSemantic() const
     {
         return hasAttribute(SEMANTIC_ATTRIBUTE);
@@ -340,7 +340,7 @@ class MX_CORE_API TypeDef : public Element
         setAttribute(CONTEXT_ATTRIBUTE, context);
     }
 
-    /// Return true if the given TypeDef has a context string.
+    /// Return true if this TypeDef has a context string.
     bool hasContext() const
     {
         return hasAttribute(CONTEXT_ATTRIBUTE);
@@ -458,18 +458,18 @@ class MX_CORE_API UnitDef : public Element
     /// @{
 
     /// Set the element's unittype string.
-    void setUnitType(const string& type)
+    void setUnitType(const string& unitType)
     {
-        setAttribute(UNITTYPE_ATTRIBUTE, type);
+        setAttribute(UNITTYPE_ATTRIBUTE, unitType);
     }
 
-    /// Return true if the given element has a unittype string.
+    /// Return true if this element has a unittype string.
     bool hasUnitType() const
     {
         return hasAttribute(UNITTYPE_ATTRIBUTE);
     }
 
-    /// Return the element's type string.
+    /// Return the element's unittype string.
     const string& getUnitType() const
     {
         return getAttribute(UNITTYPE_ATTRIBUTE);
@@ -480,14 +480,14 @@ class MX_CORE_API UnitDef : public Element
     /// @{
 
     /// Add a Unit to the UnitDef.
-    /// @param name The name of the new Unit. An exception is thrown
-    /// if the name provided is an empty string.
+    /// @param name The name of the new Unit.
     /// @return A shared pointer to the new Unit.
+    /// @throws Exception if an empty name is given.
     UnitPtr addUnit(const string& name)
     {
         if (name.empty())
         {
-            throw Exception("A unit definition name cannot be empty");
+            throw Exception("A unit name cannot be empty");
         }
         return addChild<Unit>(name);
     }
@@ -571,19 +571,19 @@ class MX_CORE_API AttributeDef : public TypedElement
     /// @name Value String
     /// @{
 
-    /// Set the value string of an element.
+    /// Set the value string of the element.
     void setValueString(const string& value)
     {
         setAttribute(VALUE_ATTRIBUTE, value);
     }
 
-    /// Return true if the given element has a value string.
+    /// Return true if this element has a value string.
     bool hasValueString() const
     {
         return hasAttribute(VALUE_ATTRIBUTE);
     }
 
-    /// Get the value string of a element.
+    /// Return the value string of the element.
     const string& getValueString() const
     {
         return getAttribute(VALUE_ATTRIBUTE);
@@ -650,13 +650,13 @@ class MX_CORE_API AttributeDef : public TypedElement
     /// @name Exportable
     /// @{
 
-    /// Set the exportable boolean for the element.
+    /// Set the exportable flag for the element.
     void setExportable(bool value)
     {
         setTypedAttribute<bool>(EXPORTABLE_ATTRIBUTE, value);
     }
 
-    /// Return the exportable boolean for the element.
+    /// Return the exportable flag for the element.
     /// Defaults to false if exportable is not set.
     bool getExportable() const
     {
diff --git a/source/MaterialXCore/Document.h b/source/MaterialXCore/Document.h
index 8f5abbf8fb..49fd4664a9 100644
--- a/source/MaterialXCore/Document.h
+++ b/source/MaterialXCore/Document.h
@@ -59,7 +59,7 @@ class MX_CORE_API Document : public GraphElement
     /// @param library The library document to be imported.
     void importLibrary(const ConstDocumentPtr& library);
 
-    /// Get a list of source URI's referenced by the document
+    /// Get a list of source URI's referenced by the document.
     StringSet getReferencedSourceUris() const;
 
     /// @name NodeGraph Elements
@@ -338,13 +338,18 @@ class MX_CORE_API Document : public GraphElement
     /// @param nodeDefName Declaration name
     /// @param node Node type for the new declaration
     /// @param version Version for the new declaration
-    /// @param isDefaultVersion If a version is specified is thie definition the default version
+    /// @param isDefaultVersion Flag that specifies whether the given `version` is the default version.
     /// @param newGraphName Make a copy of this NodeGraph with the given name if a non-empty name is provided. Otherwise
-    ///        modify the existing NodeGraph. Default value is an empty string.
-    /// @param nodeGroup Optional node group for the new declaration. The Default value is an emptry string.
+    ///        modify the existing NodeGraph.
+    /// @param nodeGroup Optional node group for the new declaration.
     /// @return New declaration if successful.
-    NodeDefPtr addNodeDefFromGraph(const NodeGraphPtr nodeGraph, const string& nodeDefName, const string& node, const string& version,
-                                   bool isDefaultVersion, const string& nodeGroup, const string& newGraphName);
+    NodeDefPtr addNodeDefFromGraph(const NodeGraphPtr nodeGraph,
+                                   const string& nodeDefName,
+                                   const string& node,
+                                   const string& version,
+                                   bool isDefaultVersion,
+                                   const string& nodeGroup,
+                                   const string& newGraphName);
 
     /// Return the NodeDef, if any, with the given name.
     NodeDefPtr getNodeDef(const string& name) const
@@ -403,7 +408,7 @@ class MX_CORE_API Document : public GraphElement
     /// @name TargetDef Elements
     /// @{
 
-    /// Add an TargetDef to the document.
+    /// Add a TargetDef to the document.
     /// @param name The name of the new TargetDef.
     ///     If no name is specified, then a unique name will automatically be
     ///     generated.
@@ -413,7 +418,7 @@ class MX_CORE_API Document : public GraphElement
         return addChild<TargetDef>(name);
     }
 
-    /// Return the AttributeDef, if any, with the given name.
+    /// Return the TargetDef, if any, with the given name.
     TargetDefPtr getTargetDef(const string& name) const
     {
         return getChildOfType<TargetDef>(name);
@@ -536,6 +541,10 @@ class MX_CORE_API Document : public GraphElement
     /// @name UnitDef Elements
     /// @{
 
+    /// Add a UnitDef to the document.
+    /// @param name The name of the new UnitDef.
+    /// @return A shared pointer to the new UnitDef.
+    /// @throws Exception if an empty name is given.
     UnitDefPtr addUnitDef(const string& name)
     {
         if (name.empty())
@@ -551,7 +560,7 @@ class MX_CORE_API Document : public GraphElement
         return getChildOfType<UnitDef>(name);
     }
 
-    /// Return a vector of all Member elements in the TypeDef.
+    /// Return a vector of all UnitDef elements in the document.
     vector<UnitDefPtr> getUnitDefs() const
     {
         return getChildrenOfType<UnitDef>();
@@ -567,6 +576,10 @@ class MX_CORE_API Document : public GraphElement
     /// @name UnitTypeDef Elements
     /// @{
 
+    /// Add a UnitTypeDef to the document.
+    /// @param name The name of the new UnitTypeDef.
+    /// @return A shared pointer to the new UnitTypeDef.
+    /// @throws Exception if an empty name is given.
     UnitTypeDefPtr addUnitTypeDef(const string& name)
     {
         if (name.empty())
diff --git a/source/MaterialXCore/Element.h b/source/MaterialXCore/Element.h
index 0e00bf596a..25ec4cad2c 100644
--- a/source/MaterialXCore/Element.h
+++ b/source/MaterialXCore/Element.h
@@ -1053,14 +1053,14 @@ class MX_CORE_API ValueElement : public TypedElement
         return getAttribute(UNIT_ATTRIBUTE);
     }
 
-    /// Return the unit defined by the assocaited NodeDef if this element
+    /// Return the unit defined by the associated NodeDef if this element
     /// is a child of a Node.
     const string& getActiveUnit() const;
 
     /// Set the unit type of an element.
-    void setUnitType(const string& unit)
+    void setUnitType(const string& unitType)
     {
-        setAttribute(UNITTYPE_ATTRIBUTE, unit);
+        setAttribute(UNITTYPE_ATTRIBUTE, unitType);
     }
 
     /// Return true if the given element has a unit type.
@@ -1085,7 +1085,7 @@ class MX_CORE_API ValueElement : public TypedElement
         setTypedAttribute<bool>(UNIFORM_ATTRIBUTE, value);
     }
 
-    /// The the uniform attribute flag for this element.
+    /// Return the uniform attribute flag for this element.
     bool getIsUniform() const
     {
         return getTypedAttribute<bool>(UNIFORM_ATTRIBUTE);
diff --git a/source/MaterialXCore/Geom.h b/source/MaterialXCore/Geom.h
index f008a26419..0a406611b9 100644
--- a/source/MaterialXCore/Geom.h
+++ b/source/MaterialXCore/Geom.h
@@ -405,9 +405,9 @@ class MX_CORE_API GeomPropDef : public TypedElement
     /// @{
 
     /// Set the index string of this element.
-    void setIndex(const string& space)
+    void setIndex(const string& index)
     {
-        setAttribute(INDEX_ATTRIBUTE, space);
+        setAttribute(INDEX_ATTRIBUTE, index);
     }
 
     /// Return true if this element has an index string.
diff --git a/source/MaterialXCore/Interface.h b/source/MaterialXCore/Interface.h
index 0773d5f836..af5f1e0a4f 100644
--- a/source/MaterialXCore/Interface.h
+++ b/source/MaterialXCore/Interface.h
@@ -69,9 +69,9 @@ class MX_CORE_API PortElement : public ValueElement
 
     /// Set the node name string of this element, creating a connection to
     /// the Node with the given name within the same NodeGraph.
-    void setNodeName(const string& node)
+    void setNodeName(const string& nodeName)
     {
-        setAttribute(NODE_NAME_ATTRIBUTE, node);
+        setAttribute(NODE_NAME_ATTRIBUTE, nodeName);
     }
 
     /// Return true if this element has a node name string.
@@ -91,9 +91,9 @@ class MX_CORE_API PortElement : public ValueElement
     /// @{
 
     /// Set the node graph string of this element.
-    void setNodeGraphString(const string& node)
+    void setNodeGraphString(const string& nodeGraph)
     {
-        setAttribute(NODE_GRAPH_ATTRIBUTE, node);
+        setAttribute(NODE_GRAPH_ATTRIBUTE, nodeGraph);
     }
 
     /// Return true if this element has a node graph string.
@@ -219,19 +219,19 @@ class MX_CORE_API Input : public PortElement
     /// @name Default Geometric Property
     /// @{
 
-    /// Set the defaultgeomprop string for the input.
+    /// Set the defaultgeomprop string for this input.
     void setDefaultGeomPropString(const string& geomprop)
     {
         setAttribute(DEFAULT_GEOM_PROP_ATTRIBUTE, geomprop);
     }
 
-    /// Return true if the given input has a defaultgeomprop string.
+    /// Return true if this input has a defaultgeomprop string.
     bool hasDefaultGeomPropString() const
     {
         return hasAttribute(DEFAULT_GEOM_PROP_ATTRIBUTE);
     }
 
-    /// Return the defaultgeomprop string for the input.
+    /// Return the defaultgeomprop string for this input.
     const string& getDefaultGeomPropString() const
     {
         return getAttribute(DEFAULT_GEOM_PROP_ATTRIBUTE);
@@ -341,7 +341,7 @@ class MX_CORE_API InterfaceElement : public TypedElement
         setAttribute(NODE_DEF_ATTRIBUTE, nodeDef);
     }
 
-    /// Return true if the given interface has a NodeDef string.
+    /// Return true if this interface has a NodeDef string.
     bool hasNodeDefString() const
     {
         return hasAttribute(NODE_DEF_ATTRIBUTE);
@@ -453,13 +453,13 @@ class MX_CORE_API InterfaceElement : public TypedElement
     /// taking inheritance into account.
     vector<OutputPtr> getActiveOutputs() const;
 
-    /// Set the output to which the given input is connected, creating a
-    /// child input if needed.  If the node argument is null, then any
+    /// Set the output to which the specified input is connected, creating a
+    /// child input if needed. If the output argument is null, then any
     /// existing output connection on the input will be cleared.
     void setConnectedOutput(const string& inputName, OutputPtr output);
 
-    /// Return the output connected to the given input.  If the given input is
-    /// not present, then an empty OutputPtr is returned.
+    /// Return the output connected to the specified input. If the specified
+    /// input is not present, then an empty OutputPtr is returned.
     OutputPtr getConnectedOutput(const string& inputName) const;
 
     /// @}
@@ -571,7 +571,7 @@ class MX_CORE_API InterfaceElement : public TypedElement
         setAttribute(TARGET_ATTRIBUTE, target);
     }
 
-    /// Return true if the given interface has a target string.
+    /// Return true if this interface has a target string.
     bool hasTarget() const
     {
         return hasAttribute(TARGET_ATTRIBUTE);
diff --git a/source/MaterialXCore/Look.h b/source/MaterialXCore/Look.h
index dadc54c72e..a5ce0964fd 100644
--- a/source/MaterialXCore/Look.h
+++ b/source/MaterialXCore/Look.h
@@ -300,7 +300,7 @@ class MX_CORE_API MaterialAssign : public GeomElement
         setAttribute(MATERIAL_ATTRIBUTE, material);
     }
 
-    /// Return true if the given MaterialAssign has a material string.
+    /// Return true if this MaterialAssign has a material string.
     bool hasMaterial() const
     {
         return hasAttribute(MATERIAL_ATTRIBUTE);
@@ -312,20 +312,20 @@ class MX_CORE_API MaterialAssign : public GeomElement
         return getAttribute(MATERIAL_ATTRIBUTE);
     }
 
-    ///  Return the outputs on any referenced material
+    /// Return the outputs on any referenced material.
     vector<OutputPtr> getMaterialOutputs() const;
 
     /// @}
     /// @name Exclusive
     /// @{
 
-    /// Set the exclusive boolean for the MaterialAssign.
+    /// Set the exclusive flag for the MaterialAssign.
     void setExclusive(bool value)
     {
         setTypedAttribute<bool>(EXCLUSIVE_ATTRIBUTE, value);
     }
 
-    /// Return the exclusive boolean for the MaterialAssign.
+    /// Return the exclusive flag for the MaterialAssign.
     bool getExclusive() const
     {
         return getTypedAttribute<bool>(EXCLUSIVE_ATTRIBUTE);
@@ -406,7 +406,7 @@ class MX_CORE_API Visibility : public GeomElement
         setAttribute(VIEWER_GEOM_ATTRIBUTE, geom);
     }
 
-    /// Return true if the given element has a viewer geom string.
+    /// Return true if this element has a viewer geom string.
     bool hasViewerGeom() const
     {
         return hasAttribute(VIEWER_GEOM_ATTRIBUTE);
@@ -422,13 +422,13 @@ class MX_CORE_API Visibility : public GeomElement
     /// @name Viewer Collection
     /// @{
 
-    /// Set the viewer geom string of the element.
+    /// Set the viewer collection string of the element.
     void setViewerCollection(const string& collection)
     {
         setAttribute(VIEWER_COLLECTION_ATTRIBUTE, collection);
     }
 
-    /// Return true if the given element has a viewer collection string.
+    /// Return true if this element has a viewer collection string.
     bool hasViewerCollection() const
     {
         return hasAttribute(VIEWER_COLLECTION_ATTRIBUTE);
@@ -450,7 +450,7 @@ class MX_CORE_API Visibility : public GeomElement
         setAttribute(VISIBILITY_TYPE_ATTRIBUTE, type);
     }
 
-    /// Return true if the given element has a visibility type string.
+    /// Return true if this element has a visibility type string.
     bool hasVisibilityType() const
     {
         return hasAttribute(VISIBILITY_TYPE_ATTRIBUTE);
@@ -466,13 +466,13 @@ class MX_CORE_API Visibility : public GeomElement
     /// @name Visible
     /// @{
 
-    /// Set the visible boolean of the element.
+    /// Set the visible flag of the element.
     void setVisible(bool visible)
     {
         setTypedAttribute<bool>(VISIBLE_ATTRIBUTE, visible);
     }
 
-    /// Return the visible boolean of the element.
+    /// Return the visible flag of the element.
     bool getVisible() const
     {
         return getTypedAttribute<bool>(VISIBLE_ATTRIBUTE);
diff --git a/source/MaterialXCore/Node.h b/source/MaterialXCore/Node.h
index 55846cf2e3..ee306b4c33 100644
--- a/source/MaterialXCore/Node.h
+++ b/source/MaterialXCore/Node.h
@@ -108,7 +108,7 @@ class MX_CORE_API Node : public InterfaceElement
     /// @{
 
     /// Return the first implementation for this node, optionally filtered by
-    /// the given target and language names.
+    /// the given target name.
     /// @param target An optional target name, which will be used to filter
     ///    the implementations that are considered.
     /// @return An implementation for this node, or an empty shared pointer if
@@ -315,7 +315,7 @@ class MX_CORE_API GraphElement : public InterfaceElement
     NodePtr addGeomNode(ConstGeomPropDefPtr geomPropDef, const string& namePrefix);
 
     /// Convert this graph to a string in the DOT language syntax.  This can be
-    /// used to visualise the graph using GraphViz (http://www.graphviz.org).
+    /// used to visualise the graph using Graphviz (https://www.graphviz.org).
     ///
     /// If declarations for the contained nodes are provided as nodedefs in
     /// the owning document, then they will be used to provide additional
diff --git a/source/MaterialXCore/Types.h b/source/MaterialXCore/Types.h
index 5c64d0950a..783abacae8 100644
--- a/source/MaterialXCore/Types.h
+++ b/source/MaterialXCore/Types.h
@@ -349,11 +349,11 @@ class MX_CORE_API Color3 : public VectorN<Color3, float, 3>
         _arr = { r, g, b };
     }
 
-    /// Transform the given color from linear RGB to the sRGB encoding,
+    /// Transform this color from linear RGB to the sRGB encoding,
     /// returning the result as a new value.
     Color3 linearToSrgb() const;
 
-    /// Transform the given color from the sRGB encoding to linear RGB,
+    /// Transform this color from the sRGB encoding to linear RGB,
     /// returning the result as a new value.
     Color3 srgbToLinear() const;
 };
diff --git a/source/MaterialXCore/Unit.h b/source/MaterialXCore/Unit.h
index dbc63bb68e..255c5e687d 100644
--- a/source/MaterialXCore/Unit.h
+++ b/source/MaterialXCore/Unit.h
@@ -43,39 +43,39 @@ class MX_CORE_API UnitConverter
     UnitConverter() { }
     virtual ~UnitConverter() { }
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     virtual float convert(float input, const string& inputUnit, const string& outputUnit) const = 0;
 
-    /// Given a unit name return a value that it can map to as an integer
-    /// Returns -1 value if not found
+    /// Given a unit name, return a value that it can map to as an integer.
+    /// Returns -1 if unit not found.
     virtual int getUnitAsInteger(const string&) const { return -1; }
 
-    /// Given an integer index return the unit name in the map used by the converter
-    /// Returns Empty string if not found
+    /// Given an integer index return the unit name in the map used by the converter.
+    /// Returns an empty string if index not found.
     virtual string getUnitFromInteger(int) const { return EMPTY_STRING; }
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     virtual Vector2 convert(const Vector2& input, const string& inputUnit, const string& outputUnit) const = 0;
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     virtual Vector3 convert(const Vector3& input, const string& inputUnit, const string& outputUnit) const = 0;
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     virtual Vector4 convert(const Vector4& input, const string& inputUnit, const string& outputUnit) const = 0;
 
-    /// Create unit definitions in a document based on the converter
+    /// Create unit definitions in a document based on the converter.
     virtual void write(DocumentPtr doc) const = 0;
 };
 
@@ -87,15 +87,15 @@ class MX_CORE_API LinearUnitConverter : public UnitConverter
     virtual ~LinearUnitConverter() { }
 
     /// Creator
-    static LinearUnitConverterPtr create(UnitTypeDefPtr UnitDef);
+    static LinearUnitConverterPtr create(UnitTypeDefPtr unitTypeDef);
 
-    /// Return the unit type string
+    /// Return the unit type string.
     const string& getUnitType() const
     {
         return _unitType;
     }
 
-    /// Create unit definitions in a document based on the converter
+    /// Create unit definitions in a document based on the converter.
     void write(DocumentPtr doc) const override;
 
     /// @name Conversion
@@ -108,30 +108,30 @@ class MX_CORE_API LinearUnitConverter : public UnitConverter
         return _unitScale;
     }
 
-    /// Ratio between the given unit to a desired unit
+    /// Ratio between the given unit to a desired unit.
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     float conversionRatio(const string& inputUnit, const string& outputUnit) const;
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     float convert(float input, const string& inputUnit, const string& outputUnit) const override;
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     Vector2 convert(const Vector2& input, const string& inputUnit, const string& outputUnit) const override;
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
     Vector3 convert(const Vector3& input, const string& inputUnit, const string& outputUnit) const override;
 
-    /// Convert a given value in a given unit to a desired unit
+    /// Convert a given value in a given unit to a desired unit.
     /// @param input Input value to convert
     /// @param inputUnit Unit of input value
     /// @param outputUnit Unit for output value
@@ -142,11 +142,11 @@ class MX_CORE_API LinearUnitConverter : public UnitConverter
     /// @{
 
     /// Given a unit name return a value that it can map to as an integer.
-    /// Returns -1 value if not found
+    /// Returns -1 if not found.
     int getUnitAsInteger(const string& unitName) const override;
 
     /// Given an integer index return the unit name in the map used by the converter.
-    /// Returns Empty string if not found
+    /// Returns an empty string if not found.
     virtual string getUnitFromInteger(int index) const override;
 
     /// @}
@@ -173,26 +173,26 @@ class MX_CORE_API UnitConverterRegistry
     /// Creator
     static UnitConverterRegistryPtr create();
 
-    /// Add a unit converter for a given UnitDef.
-    /// Returns false if a converter has already been registered for the given UnitDef
+    /// Add a unit converter for a given UnitTypeDef.
+    /// Returns false if a converter has already been registered for the given UnitTypeDef.
     bool addUnitConverter(UnitTypeDefPtr def, UnitConverterPtr converter);
 
-    /// Remove a unit converter for a given UnitDef.
-    /// Returns false if a converter does not exist for the given UnitDef
+    /// Remove a unit converter for a given UnitTypeDef.
+    /// Returns false if a converter does not exist for the given UnitTypeDef.
     bool removeUnitConverter(UnitTypeDefPtr def);
 
-    /// Get a unit converter for a given UnitDef
-    /// Returns any empty pointer if a converter does not exist for the given UnitDef
+    /// Get a unit converter for a given UnitTypeDef.
+    /// Returns an empty pointer if a converter does not exist for the given UnitTypeDef.
     UnitConverterPtr getUnitConverter(UnitTypeDefPtr def);
 
     /// Clear all unit converters from the registry.
     void clearUnitConverters();
 
-    /// Given a unit name return a value that it can map to as an integer
-    /// Returns -1 value if not found
+    /// Given a unit name return a value that it can map to as an integer.
+    /// Returns -1 if unit not found.
     int getUnitAsInteger(const string& unitName) const;
 
-    /// Create unit definitions in a document based on registered converters
+    /// Create unit definitions in a document based on registered converters.
     void write(DocumentPtr doc) const;
 
     /// Convert input values which have a source unit to a given target unit.
diff --git a/source/MaterialXCore/Variant.h b/source/MaterialXCore/Variant.h
index 7da2fa1e78..8c8fdd898a 100644
--- a/source/MaterialXCore/Variant.h
+++ b/source/MaterialXCore/Variant.h
@@ -119,7 +119,7 @@ class MX_CORE_API VariantAssign : public Element
         setAttribute(VARIANT_SET_ATTRIBUTE, variantSet);
     }
 
-    /// Return true if the given element has a variant set string.
+    /// Return true if this element has a variant set string.
     bool hasVariantSetString() const
     {
         return hasAttribute(VARIANT_SET_ATTRIBUTE);
@@ -141,7 +141,7 @@ class MX_CORE_API VariantAssign : public Element
         setAttribute(VARIANT_ATTRIBUTE, variant);
     }
 
-    /// Return true if the given element has a variant string.
+    /// Return true if this element has a variant string.
     bool hasVariantString() const
     {
         return hasAttribute(VARIANT_ATTRIBUTE);