Add type documentation for the different light sources (#3582)

* Add type documentation for the different light sources

* Address code review comments

modules/base/lightsource/cameralightsource.cpp

@@ -37,6 +37,9 @@ namespace {
         openspace::properties::Property::Visibility::NoviceUser
     };
 
+    // This `LightSource` type represents a light source placed at the position of the
+    // camera. An object with this light source will always be illuminated from the
+    // current view direction.
     struct [[codegen::Dictionary(CameraLightSource)]] Parameters {
         // [[codegen::verbatim(IntensityInfo.description)]]
         std::optional<float> intensity;

modules/base/lightsource/scenegraphlightsource.cpp

@@ -41,18 +41,26 @@ namespace {
         openspace::properties::Property::Visibility::NoviceUser
     };
 
-    constexpr openspace::properties::Property::PropertyInfo NodeCameraStateInfo = {
+    constexpr openspace::properties::Property::PropertyInfo NodeInfo = {
         "Node",
         "Node",
         "The identifier of the scene graph node to follow.",
         openspace::properties::Property::Visibility::AdvancedUser
     };
 
+    // This `LightSource` type represents a light source placed at the position of a
+    // scene graph node. That is, the direction of the light will follow the position
+    // of an existing object in the scene. It will also update dynamically as the
+    // object moves.
+    //
+    // Note that the brightness of the light from the light source does not depend on
+    // the distance between the two scene graph nodes. Only the `Intensity` value has
+    // an impact on the brightness.
     struct [[codegen::Dictionary(SceneGraphLightSource)]] Parameters {
         // [[codegen::verbatim(IntensityInfo.description)]]
         std::optional<float> intensity;
 
-        // [[codegen::verbatim(NodeCameraStateInfo.description)]]
+        // [[codegen::verbatim(NodeInfo.description)]]
         std::string node [[codegen::identifier()]];
     };
 #include "scenegraphlightsource_codegen.cpp"
@@ -67,7 +75,7 @@ documentation::Documentation SceneGraphLightSource::Documentation() {
 SceneGraphLightSource::SceneGraphLightSource(const ghoul::Dictionary& dictionary)
     : LightSource(dictionary)
     , _intensity(IntensityInfo, 1.f, 0.f, 1.f)
-    , _sceneGraphNodeReference(NodeCameraStateInfo, "")
+    , _sceneGraphNodeReference(NodeInfo, "")
 {
     const Parameters p = codegen::bake<Parameters>(dictionary);
 

src/scene/lightsource.cpp

@@ -42,13 +42,20 @@ namespace {
         openspace::properties::Property::Visibility::AdvancedUser
     };
 
+    // This is the base class of all `LightSource` types, which are components that can be
+    // added to certain `Renderable` types to add lighting effects.
+    //
+    // A `LightSource`, in this case, is just a table that describes properties such as
+    // the location of the light. It _does not physically exist in the scene_, and the
+    // table of parameters have to be added to each `Renderable` that should be affected
+    // by the light source. This is commonly done by exporting a light source table from
+    // an Asset file that represents an illuminating object in the scene, such as the Sun
+    // in our solar system.
     struct [[codegen::Dictionary(LightSource)]] Parameters {
-        // The type of the light source that is described in this element. The available
-        // types of light sources depend on the configuration of the application and can
-        // be written to disk on application startup into the FactoryDocumentation
-        std::string type [[codegen::annotation("Must name a valid LightSource type")]];
+        // The type of light source that is described in this element.
+        std::string type [[codegen::annotation("Must name a valid `LightSource` type")]];
 
-        // The identifier of the light source
+        // The identifier of the light source.
         std::string identifier [[codegen::identifier()]];
 
         // [[codegen::verbatim(EnabledInfo.description)]]