From 3bbb50359d1fe392c1e8086e54083631a2fbdce6 Mon Sep 17 00:00:00 2001
From: Aaron Franke <arnfranke@yahoo.com>
Date: Sun, 14 Aug 2022 13:55:41 -0500
Subject: [PATCH] Document GLTFLight and GLTFSpecGloss

---
 modules/gltf/doc_classes/GLTFLight.xml     | 3 +++
 modules/gltf/doc_classes/GLTFSpecGloss.xml | 8 ++++++++
 modules/gltf/extensions/gltf_light.h       | 2 ++
 modules/gltf/extensions/gltf_spec_gloss.h  | 5 +++++
 4 files changed, 18 insertions(+)

diff --git a/modules/gltf/doc_classes/GLTFLight.xml b/modules/gltf/doc_classes/GLTFLight.xml
index 354cd48a06d1..db2dfb487aed 100644
--- a/modules/gltf/doc_classes/GLTFLight.xml
+++ b/modules/gltf/doc_classes/GLTFLight.xml
@@ -1,10 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GLTFLight" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
+		Represents a GLTF light.
 	</brief_description>
 	<description>
+		Represents a light as defined by the [code]KHR_lights_punctual[/code] GLTF extension.
 	</description>
 	<tutorials>
+		<link title="KHR_lights_punctual GLTF extension spec">https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_lights_punctual</link>
 	</tutorials>
 	<members>
 		<member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)">
diff --git a/modules/gltf/doc_classes/GLTFSpecGloss.xml b/modules/gltf/doc_classes/GLTFSpecGloss.xml
index 8433cf8dd73b..8882e4825788 100644
--- a/modules/gltf/doc_classes/GLTFSpecGloss.xml
+++ b/modules/gltf/doc_classes/GLTFSpecGloss.xml
@@ -1,21 +1,29 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="GLTFSpecGloss" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
 	<brief_description>
+		Archived GLTF extension for specular/glossy materials.
 	</brief_description>
 	<description>
+		KHR_materials_pbrSpecularGlossiness is an archived GLTF extension. This means that it is deprecated and not recommended for new files. However, it is still supported for loading old files.
 	</description>
 	<tutorials>
+		<link title="KHR_materials_pbrSpecularGlossiness GLTF extension spec">https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Archived/KHR_materials_pbrSpecularGlossiness</link>
 	</tutorials>
 	<members>
 		<member name="diffuse_factor" type="Color" setter="set_diffuse_factor" getter="get_diffuse_factor" default="Color(1, 1, 1, 1)">
+			The reflected diffuse factor of the material.
 		</member>
 		<member name="diffuse_img" type="Image" setter="set_diffuse_img" getter="get_diffuse_img">
+			The diffuse texture.
 		</member>
 		<member name="gloss_factor" type="float" setter="set_gloss_factor" getter="get_gloss_factor" default="1.0">
+			The glossiness or smoothness of the material.
 		</member>
 		<member name="spec_gloss_img" type="Image" setter="set_spec_gloss_img" getter="get_spec_gloss_img">
+			The specular-glossiness texture.
 		</member>
 		<member name="specular_factor" type="Color" setter="set_specular_factor" getter="get_specular_factor" default="Color(1, 1, 1, 1)">
+			The specular RGB color of the material. The alpha channel is unused.
 		</member>
 	</members>
 </class>
diff --git a/modules/gltf/extensions/gltf_light.h b/modules/gltf/extensions/gltf_light.h
index 58fa299dfd2a..f0765a1bbca7 100644
--- a/modules/gltf/extensions/gltf_light.h
+++ b/modules/gltf/extensions/gltf_light.h
@@ -35,6 +35,8 @@
 #include "core/io/resource.h"
 #include "scene/3d/light_3d.h"
 
+// https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_lights_punctual
+
 class GLTFLight : public Resource {
 	GDCLASS(GLTFLight, Resource)
 	friend class GLTFDocument;
diff --git a/modules/gltf/extensions/gltf_spec_gloss.h b/modules/gltf/extensions/gltf_spec_gloss.h
index a45fa4296c62..2b4d3ee609b9 100644
--- a/modules/gltf/extensions/gltf_spec_gloss.h
+++ b/modules/gltf/extensions/gltf_spec_gloss.h
@@ -34,6 +34,11 @@
 #include "core/io/image.h"
 #include "core/io/resource.h"
 
+// KHR_materials_pbrSpecularGlossiness is an archived GLTF extension.
+// This means that it is deprecated and not recommended for new files.
+// However, it is still supported for loading old files.
+// https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Archived/KHR_materials_pbrSpecularGlossiness
+
 class GLTFSpecGloss : public Resource {
 	GDCLASS(GLTFSpecGloss, Resource);
 	friend class GLTFDocument;