Feature/add some docs (#2961)

* Add docs for PathInstruction

* Add docs for renderablecartesianaxes and navigationstate

* Write docs for ExoplanetDataPreparationTask

* Add some kind of documentation for the task base class

Was already showing in the list, but the property or decription was not included

* Apply suggestions from code review

* Address review comments

* Clarify confusing sentence

* Slight rephrasing

modules/base/rendering/renderablecartesianaxes.cpp

@@ -61,6 +61,18 @@ namespace {
         openspace::properties::Property::Visibility::NoviceUser
     };
 
+    // The RenderableCartesianAxes can be used to render the local Cartesian coordinate
+    // system, or reference frame, of another scene graph node. The colors of the axes
+    // can be customized but are per default set to Red, Green and Blue, for the X-, Y-
+    // and Z-axis, respectively.
+    //
+    // To add the axes, create a scene graph node with the RenderableCartesianAxes
+    // renderable and add it as a child to the other scene graph node, i.e. specify the
+    // other node as the Parent of the node with this renderable. Also, the axes have to
+    // be scaled to match the parent object for the axes to be visible in the scene, for
+    // example using a StaticScale.
+    //
+    // See example asset (@TODO: link to asset file).
     struct [[codegen::Dictionary(RenderableCartesianAxes)]] Parameters {
         // [[codegen::verbatim(XColorInfo.description)]]
         std::optional<glm::vec3> xColor [[codegen::color()]];
@@ -70,7 +82,6 @@ namespace {
 
         // [[codegen::verbatim(ZColorInfo.description)]]
         std::optional<glm::vec3> zColor [[codegen::color()]];
-
     };
 #include "renderablecartesianaxes_codegen.cpp"
 } // namespace

modules/exoplanets/tasks/exoplanetsdatapreparationtask.cpp

@@ -40,6 +40,27 @@
 namespace {
     constexpr std::string_view _loggerCat = "ExoplanetsDataPreparationTask";
 
+    // This task is used for generating the binary data files that are used for the
+    // exoplanet system loading in OpenSpace. Using this binary file allows efficient
+    // data loading of an arbitrary exoplanet system during runtime, without keeping all
+    // data in memory.
+    //
+    // Two output files are generated, whose paths have to be specified: One binary with
+    // the data for the exoplanets (OutputBIN) and one look-up table that is used to
+    // find where in the binary file a particular system is located (OutputLUT).
+    //
+    // Additionally, the task uses three different files as input: 1) a CSV file with the
+    // data from the NASA Exoplanet Archive, 2) A SPECK file that contains star positions,
+    // and 3) a TXT file that is used for the conversion from the stars' effective
+    // temperature to a B-V color index. The paths for all these paths have to be
+    // specified. The SPECK file (2) will be used for the positions of the host stars, to
+    // make sure that they line up with the stars in that dataset. The cross-matching is
+    // done by star name, as given by the comment in the SPECK file and the host star
+    // column in the exoplanet dataset.
+    //
+    // Note that the CSV (1) has to include a certain set of columns for the rendering to
+    // be correct. Use the accompanying python script to download the datafile, or make
+    // sure to include all columns in your download.
     struct [[codegen::Dictionary(ExoplanetsDataPreparationTask)]] Parameters {
         // The csv file to extract data from
         std::string inputDataFile;

src/documentation/core_registration.cpp

@@ -57,6 +57,7 @@
 #include <openspace/scripting/scriptscheduler.h>
 #include <openspace/scripting/systemcapabilitiesbinding.h>
 #include <openspace/util/spicemanager.h>
+#include <openspace/util/task.h>
 #include <openspace/util/time.h>
 #include <openspace/util/timerange.h>
 
@@ -74,6 +75,7 @@ void registerCoreClasses(documentation::DocumentationEngine& engine) {
     engine.addDocumentation(Scale::Documentation());
     engine.addDocumentation(SceneGraphNode::Documentation());
     engine.addDocumentation(ScreenSpaceRenderable::Documentation());
+    engine.addDocumentation(Task::documentation());
     engine.addDocumentation(TimeRange::Documentation());
     engine.addDocumentation(Translation::Documentation());
     engine.addDocumentation(TimeFrame::Documentation());

src/navigation/navigationstate.cpp

@@ -33,6 +33,24 @@ namespace {
 
     constexpr double Epsilon = 1E-7;
 
+    // A NavigationState is an object describing an exact camera position and rotation,
+    // in a certain reference frame (per default, the one of the specified Anchor node).
+    // It can be used to set the same camera position at a later point in time, or
+    // navigating to a specific camera position using the pathnavigation system.
+    //
+    // The camera rotation is specified using Euler angles, in radians. It is also
+    // possible to specify a node to be used as Aim, but note that this will not affect
+    // the actual camera position or view direction.
+    //
+    // To get the current navigation state of the camera, use the
+    // `openspace.navigation.getNavigationState()` function in the Scripting API.
+    //
+    // Note that a NavigationState does not include information about what timestamp
+    // within OpenSpace that the NavigationState was generated. When laoding a
+    // NavigationState, the visuals may be different depending on what the simulation
+    // timestamp is, as the relative positions of objects in the scene may have changed.
+    // The get the exact same visuals as when the NavigationState was saved, make sure
+    // to also set the time to be the same as on save.
     struct [[codegen::Dictionary(NavigationState)]] Parameters {
         // The identifier of the anchor node
         std::string anchor;

src/navigation/path.cpp

@@ -45,9 +45,24 @@ namespace {
     constexpr std::string_view _loggerCat = "Path";
     constexpr float LengthEpsilon = 1e-5f;
 
-    // TODO: where should this documentation be?
-    // It's nice to have these to interpret the dictionary when creating the path, but
-    // maybe it's not really necessary
+    // A PathInstruction is a table describing the specification for a camera path.
+    // It is used as an input to the `openspace.pathnavigation.createPath` function.
+    //
+    // There are two types of paths that can be created, as specified by the required
+    // TargetType parameter: 'Node' or 'NavigationState'. The difference is what kind
+    // of target the path is created for, a scene graph node or a specific navigation
+    // state for the camera.
+    //
+    // Depending on the type, the parameters that can be specified are a bit different.
+    // A 'NavigationState' already contains all details for the camera position, so no
+    // other details may be specified. For a 'Node' instruction, only a 'Target' node is
+    // required, but a 'Height' or 'Position' may also be specified. If both a position
+    // and height is specified, the height value will be ignored.
+    //
+    // For 'Node' paths it is also possible to specify whether the target camera state
+    // at the end of the flight should take the up direction of the target node into
+    // account. Note that for this to give an effect on the path, rolling motions have
+    // to be enabled.
     struct [[codegen::Dictionary(PathInstruction)]] Parameters {
         // The type of the instruction. Decides what other parameters are
         // handled/available
@@ -61,7 +76,7 @@ namespace {
         std::optional<float> duration;
 
         // (Node): The target node of the camera path. Not optional for 'Node'
-        // instructions
+        // type instructions
         std::optional<std::string> target;
 
         // (Node): An optional position in relation to the target node, in model
@@ -76,7 +91,7 @@ namespace {
         std::optional<bool> useTargetUpDirection;
 
         // (NavigationState): A navigation state that will be the target
-        // of this path segment
+        // of the resulting path
         std::optional<ghoul::Dictionary> navigationState
             [[codegen::reference("core_navigation_state")]];
 

src/util/task.cpp

@@ -31,6 +31,15 @@
 #include <ghoul/misc/templatefactory.h>
 
 namespace {
+
+    // The base class of all tasks. Specify the Type property to create one of the
+    // available task types. This property should be included in the same table object
+    // as the properties of the specific task.
+    //
+    // Tasks can be executed using the separate TaskRunner application. When starting the
+    // application, just enter the path to the file describing the task you want to run
+    // as input in the command line to initiate the run. All tasks should live in the task
+    // folder in the data folder of the OpenSpace installation.
     struct [[codegen::Dictionary(Task)]] Parameters {
         // This key specifies the type of Task that gets created. It has to be one of the
         // valid Tasks that are available for creation (see the FactoryDocumentation for a