diff --git a/Doxyfile b/Doxyfile index 44468a071b..6417b0167a 100644 --- a/Doxyfile +++ b/Doxyfile @@ -947,6 +947,7 @@ INPUT = src \ include \ modules \ apps \ + ext/ghoul \ support/doxygen/README.md # This tag can be used to specify the character encoding of the source files @@ -987,9 +988,7 @@ INPUT_FILE_ENCODING = # provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, # *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice. -FILE_PATTERNS = *.cpp \ - *.h \ - *.inl +FILE_PATTERNS = *.cpp *.h *.inl # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -1020,16 +1019,16 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = ext/* \ - bin/* \ - build/* \ - config/* \ - gui/* \ - kernels/* \ - data/* \ - scripts/* \ - shaders/* \ - **/ext/** +EXCLUDE_PATTERNS = */ext/curl \ + */ext/date \ + */ext/json \ + */ext/spice \ + */ext/vld \ + */ext/tinythread \ + */ext/ghoul/ext/* \ + */modules/*/ext/* \ + */apps/OpenSpace-MinVR/ext/* \ + */apps/OpenSpace/ext/sgct/ext/* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/ext/ghoul b/ext/ghoul index fbd80eae0f..c2992bd52f 160000 --- a/ext/ghoul +++ b/ext/ghoul @@ -1 +1 @@ -Subproject commit fbd80eae0ff589a9fa2fb5e2c8af8e4491fe4e2d +Subproject commit c2992bd52f7c4e29a85dcbe44e3e6a89ffec0c19 diff --git a/include/openspace/documentation/documentation.h b/include/openspace/documentation/documentation.h index c8c7385613..28d2029922 100644 --- a/include/openspace/documentation/documentation.h +++ b/include/openspace/documentation/documentation.h @@ -56,11 +56,16 @@ struct TestResult { struct Offense { /// The Reason for the offense enum class Reason { - Unknown, ///< Unknown reason - MissingKey, ///< The offending key that was requested was not found - WrongType, ///< The key's value was not of the expected type - Verification, ///< The value did not pass a necessary non-type verifier - UnknownIdentifier ///< The identifier for a ReferencingVerifier did not exist + /// Unknown reason + Unknown, + /// The offending key that was requested was not found + MissingKey, + /// The key's value was not of the expected type + WrongType, + /// The value did not pass a necessary non-type verifier + Verification, + /// The identifier for a ReferencingVerifier did not exist + UnknownIdentifier }; /// The offending key that caused the Offense. In the case of a nested table, /// this value will be the fully qualified name of the key @@ -80,7 +85,8 @@ struct TestResult { struct Warning { /// The reason for the warning enum class Reason { - Deprecated ///< The value is marked as deprecated and should not used + /// The value is marked as deprecated and should not used + Deprecated }; /// The offending key that caused the Warning. In the case of a nested table, @@ -90,7 +96,6 @@ struct TestResult { Reason reason; }; - /// Is `true` if the TestResult is positive, `false` otherwise bool success = false; /// Contains a list of offenses that were found in the test. Is empty if @@ -130,10 +135,10 @@ void logError(const SpecificationError& error, std::string component = ""); * DocumentationEntry::Wildcard, any key in the containing Documentation will be tested * against the provided verifier. The most convenient way of creating DocumentationEntry%s * is by using an inline initializer list such as: - *\verbatim -DocumentationEntry e = { "key", new IntVerifier, "Documentation text", Optional::Yes }; -\endverbatim - + * ``` + * DocumentationEntry e = { "key", new IntVerifier, "Documentation text", Optional::Yes }; + * ``` + * * Furthermore, these initializer lists can be crated all at once for a Documentation. * Even if the Verifier%s are specified using the `new` operators, they will not leak * memory as the DocumentationEntry takes ownership of them in the constructor. @@ -190,8 +195,7 @@ struct DocumentationEntry { * \pre \p k must not be empty * \pre \p v must not be nullptr */ - DocumentationEntry(std::string k, Verifier* v, Optional opt, - std::string doc = ""); + DocumentationEntry(std::string k, Verifier* v, Optional opt, std::string doc = ""); /// The key that is described by this DocumentationEntry std::string key; @@ -203,7 +207,6 @@ struct DocumentationEntry { std::string documentation; }; - /** * This struct contains the documentation and specification for a ghoul::Dictionary. It is * used to impose restrictions on keys and values and determine whether a given @@ -211,16 +214,16 @@ struct DocumentationEntry { * #testSpecificationAndThrow methods). Each Documentation consists of a human-readable * `name`, and a list of DocumentationEntry%s that each describe a single key value. The * most convenient way of creating a Documentation is by using nested initializer lists: - *\verbatim -Documentation doc = { - "Documentation for an arbitrary dictionary", - { // A list of DocumentationEntry%s; also specified using initializer lists - { "key1", new IntVerifier, "Documentation key1", Optional::Yes }, - { "key2", new FloatVerifier, "Documentation key2" }, - { "key3", new StringVerifier } - } -}; -\endverbatim + * ``` + * Documentation doc = { + * "Documentation for an arbitrary dictionary", + * { // A list of DocumentationEntry%s; also specified using initializer lists + * { "key1", new IntVerifier, "Documentation key1", Optional::Yes }, + * { "key2", new FloatVerifier, "Documentation key2" }, + * { "key3", new StringVerifier } + * } + * }; + * ``` * * If multiple DocumentationEntries cover the same key, they are all evaluated for that * specific key. The same holds true if there is a DocumentationEntry with a diff --git a/include/openspace/documentation/documentationengine.h b/include/openspace/documentation/documentationengine.h index 88ec3042c7..a21f563b90 100644 --- a/include/openspace/documentation/documentationengine.h +++ b/include/openspace/documentation/documentationengine.h @@ -47,8 +47,7 @@ public: * Constructor of a DuplicateDocumentationException storing the offending * Documentation for later use. * - * \param doc The Documentation whose identifier was previously - * registered + * \param doc The Documentation whose identifier was previously registered */ DuplicateDocumentationException(Documentation doc); @@ -92,7 +91,6 @@ public: nlohmann::json generateJsonJson() const; private: - /// The list of all Documentation%s that are stored by the DocumentationEngine std::vector _documentations; diff --git a/include/openspace/documentation/verifier.h b/include/openspace/documentation/verifier.h index 5eeeba1c1b..fc7cc06b71 100644 --- a/include/openspace/documentation/verifier.h +++ b/include/openspace/documentation/verifier.h @@ -58,7 +58,7 @@ public: * \return A TestResult struct that contains information about whether the key adheres * to the demands of the specific Verifier. If it does not, * TestResult::offenders will either contain \p key or, in the case of a - * TableVerifier, a list of all offending subkeys as fully qualified names. + * TableVerifier, a list of all offending subkeys as fully qualified names * * \post If the return values' TestResult::success is `true`, its * TestResult::offenders is empty @@ -98,6 +98,7 @@ public: * The base class Verifier for all Verifier%s that have to test against a specific value * type. This Verifier tests whether a given key exists and whether it has the same type * as the template parameter `T`. + * * \tparam T The type against which the key's value is tested */ template @@ -112,7 +113,7 @@ public: * \param dictionary The ghoul::Dictionary that contains the \p key to be tested * \param key The key inside the \p dictinoary that is to be tested * \return A TestResult that contains the information whether the \p key exists in the - * \p dictionary and whether the key's value's type agrees with `T`. + * \p dictionary and whether the key's value's type agrees with `T` * * \post The return values' TestResult::success is either `true` and * TestResult::offenders is empty, or it is `false` and TestResult::offenders @@ -220,7 +221,7 @@ public: /** * A Verifier that checks whether a given key inside a ghoul::Dictionary is a string and - * a valid date time + * a valid date time. */ class DateTimeVerifier : public StringVerifier { public: @@ -312,21 +313,27 @@ public: // Vector verifiers //---------------------------------------------------------------------------------------- -/// This Verifier checks whether the value is of type `glm::tvec2` +/** + * This Verifier checks whether the value is of type `glm::tvec2`. + */ template class Vector2Verifier : public TemplateVerifier> { public: std::string type() const override; }; -/// This Verifier checks whether the value is of type `glm::tvec3` +/** + * This Verifier checks whether the value is of type `glm::tvec3`. + */ template class Vector3Verifier : public TemplateVerifier> { public: std::string type() const override; }; -/// This Verifier checks whether the value is of type `glm::tvec4` +/** + * This Verifier checks whether the value is of type `glm::tvec4`. + */ template class Vector4Verifier : public TemplateVerifier> { public: @@ -351,7 +358,7 @@ public: /** * A Verifier that checks whether all values contained in a Table are of - * type `glm::tvec2` + * type `glm::tvec2`. */ template class Vector2ListVerifier : public TableVerifier { @@ -369,7 +376,7 @@ public: /** * A Verifier that checks whether all values contained in a Table are of - * type `glm::tvec3` + * type `glm::tvec3`. */ template class Vector3ListVerifier : public TableVerifier { @@ -387,7 +394,7 @@ public: /** * A Verifier that checks whether all values contained in a Table are of - * type `glm::tvec4` + * type `glm::tvec4`. */ template class Vector4ListVerifier : public TableVerifier { @@ -408,7 +415,7 @@ public: //---------------------------------------------------------------------------------------- /** - * This Verifier checks whether the value is of type `glm::mat2x2` + * This Verifier checks whether the value is of type `glm::mat2x2`. */ template class Matrix2x2Verifier : public TemplateVerifier> { @@ -417,7 +424,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat2x3` + * This Verifier checks whether the value is of type `glm::mat2x3`. */ template class Matrix2x3Verifier : public TemplateVerifier> { @@ -426,7 +433,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat2x4` + * This Verifier checks whether the value is of type `glm::mat2x4`. */ template class Matrix2x4Verifier : public TemplateVerifier> { @@ -435,7 +442,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat3x2` + * This Verifier checks whether the value is of type `glm::mat3x2`. */ template class Matrix3x2Verifier : public TemplateVerifier> { @@ -444,7 +451,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat3x3` + * This Verifier checks whether the value is of type `glm::mat3x3`. */ template class Matrix3x3Verifier : public TemplateVerifier> { @@ -453,7 +460,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat3x4` + * This Verifier checks whether the value is of type `glm::mat3x4`. */ template class Matrix3x4Verifier : public TemplateVerifier> { @@ -462,7 +469,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat4x2` + * This Verifier checks whether the value is of type `glm::mat4x2`. */ template class Matrix4x2Verifier : public TemplateVerifier> { @@ -471,7 +478,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat4x3` + * This Verifier checks whether the value is of type `glm::mat4x3`. */ template class Matrix4x3Verifier : public TemplateVerifier> { @@ -480,7 +487,7 @@ public: }; /** - * This Verifier checks whether the value is of type `glm::mat4x4` + * This Verifier checks whether the value is of type `glm::mat4x4`. */ template class Matrix4x4Verifier : public TemplateVerifier> { @@ -513,6 +520,7 @@ public: /** * Constructor for an OperatorVerifier. As all operators need to compare the incoming * value to a stored value, we require the comparison \p value to be passed in here. + * * \param value The value against which the tested value is compared using the * `Operator` */ @@ -530,7 +538,7 @@ public: * \p key%'s value has the wrong type, it will be added to the TestResult's * offense list with the reason TestResult::Offense::Reason::WrongType; if the * `Operator` returns false, it will be added with the reason - * TestResult::Offense::Verification instead. + * TestResult::Offense::Verification instead */ TestResult operator()(const ghoul::Dictionary& dictionary, const std::string& key) const override; @@ -683,7 +691,7 @@ public: * \p key%'s value has the wrong type, it will be added to the TestResult's * offense list with the reason TestResult::Offense::Reason::WrongType; if the * value is not in the list, it will be added with the reason - * TestResult::Offense::Verification instead. + * TestResult::Offense::Verification instead */ TestResult operator()(const ghoul::Dictionary& dictionary, const std::string& key) const override; @@ -725,7 +733,7 @@ public: * \p key%'s value has the wrong type, it will be added to the TestResult's * offense list with the reason TestResult::Offense::Reason::WrongType; if the * value is in the list, it will be added with the reason - * TestResult::Offense::Verification instead. + * TestResult::Offense::Verification instead */ TestResult operator()(const ghoul::Dictionary& dictionary, const std::string& key) const override; @@ -777,7 +785,7 @@ public: * offense list with the reason TestResult::Offense::Reason::WrongType; if the * value is outside the range defined by the lower and upper limits passed to * the constructor, it will be added with the reason - * TestResult::Offense::Verification instead. + * TestResult::Offense::Verification instead */ TestResult operator()(const ghoul::Dictionary& dictionary, const std::string& key) const override; @@ -827,7 +835,7 @@ public: * offense list with the reason TestResult::Offense::Reason::WrongType; if the * value is greater or equal to the lower limit and less or equal to the upper * limit, it will be added with the reason TestResult::Offense::Verification - * instead. + * instead */ TestResult operator()(const ghoul::Dictionary& dictionary, const std::string& key) const override; @@ -863,7 +871,7 @@ public: * passed to the user when a documentation is requested. * * \param annotation The annotation that is stored and returned to the user when it - * is requested. + * is requested * * \pre annotation must not be empty */ @@ -961,7 +969,7 @@ public: * TestResult::offenses list contains \p with a reason of * TestResult::Offense::Reason::Verification. If \p key%'s value passes either * of the two Verifier%s, the result's TestResult::success is `true` and the - * TestResult::offenses is empty. + * TestResult::offenses is empty */ TestResult operator()(const ghoul::Dictionary& dictionary, const std::string& key) const override; @@ -972,118 +980,271 @@ public: std::vector> values; }; -/// A short-hand definition for a Verifier checking for `glm::bvec2` +/** + * A short-hand definition for a Verifier checking for `glm::bvec2`. + */ using BoolVector2Verifier = Vector2Verifier; -/// A short-hand definition for a Verifier checking for `glm::ivec2` + +/** + * A short-hand definition for a Verifier checking for `glm::ivec2`. + */ using IntVector2Verifier = Vector2Verifier; -/// A short-hand definition for a Verifier checking for `glm::dvec2` + +/** + * A short-hand definition for a Verifier checking for `glm::dvec2`. + */ using DoubleVector2Verifier = Vector2Verifier; -/// A short-hand definition for a Verifier checking for `glm::bvec3` + +/** + * A short-hand definition for a Verifier checking for `glm::bvec3`. + */ using BoolVector3Verifier = Vector3Verifier; -/// A short-hand definition for a Verifier checking for `glm::ivec3` + +/** + * A short-hand definition for a Verifier checking for `glm::ivec3`. + */ using IntVector3Verifier = Vector3Verifier; -/// A short-hand definition for a Verifier checking for `glm::dvec3` + +/** + * A short-hand definition for a Verifier checking for `glm::dvec3`. + */ using DoubleVector3Verifier = Vector3Verifier; -/// A short-hand definition for a Verifier checking for `glm::bvec4` + +/** + * A short-hand definition for a Verifier checking for `glm::bvec4`. + */ using BoolVector4Verifier = Vector4Verifier; -/// A short-hand definition for a Verifier checking for `glm::ivec4` + +/** + * A short-hand definition for a Verifier checking for `glm::ivec4`. + */ using IntVector4Verifier = Vector4Verifier; -/// A short-hand definition for a Verifier checking for `glm::dvec4` + +/** + * A short-hand definition for a Verifier checking for `glm::dvec4`. + */ using DoubleVector4Verifier = Vector4Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat2x2` +/** + * A short-hand definition for a Verifier checking for `glm::dmat2x2`. + */ using DoubleMatrix2x2Verifier = Matrix2x2Verifier; + using DoubleMatrix2Verifier = DoubleMatrix2x2Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat2x3` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat2x3`. + */ using DoubleMatrix2x3Verifier = Matrix2x3Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat2x4` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat2x4`. + */ using DoubleMatrix2x4Verifier = Matrix2x4Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat3x2` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat3x2`. + */ using DoubleMatrix3x2Verifier = Matrix3x2Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat3x3` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat3x3`. + */ using DoubleMatrix3x3Verifier = Matrix3x3Verifier; + using DoubleMatrix3Verifier = DoubleMatrix3x3Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat3x4` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat3x4`. + */ using DoubleMatrix3x4Verifier = Matrix3x4Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat4x2` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat4x2`. + */ using DoubleMatrix4x2Verifier = Matrix4x2Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat4x3` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat4x3`. + */ using DoubleMatrix4x3Verifier = Matrix4x3Verifier; -/// A short-hand definition for a Verifier checking for `glm::dmat4x4` + +/** + * A short-hand definition for a Verifier checking for `glm::dmat4x4`. + */ using DoubleMatrix4x4Verifier = Matrix4x4Verifier; + using DoubleMatrix4Verifier = DoubleMatrix4x4Verifier; -/// A short-hand definition for a LessVerifier with a type check for `int` +/** + * A short-hand definition for a LessVerifier with a type check for `int`. + */ using IntLessVerifier = LessVerifier; -/// A short-hand definition for a LessVerifier with a type check for `double` + +/** + * A short-hand definition for a LessVerifier with a type check for `double`. + */ using DoubleLessVerifier = LessVerifier; -/// A short-hand definition for a LessEqualVerifier with a type check for `int` + +/** + * A short-hand definition for a LessEqualVerifier with a type check for `int`. + */ using IntLessEqualVerifier = LessEqualVerifier; -/// A short-hand definition for a LessEqualVerifier with a type check for `double` + +/** + * A short-hand definition for a LessEqualVerifier with a type check for `double`. + */ using DoubleLessEqualVerifier = LessEqualVerifier; -/// A short-hand definition for a GreaterVerifier with a type check for `int` + +/** + * A short-hand definition for a GreaterVerifier with a type check for `int`. + */ using IntGreaterVerifier = GreaterVerifier; -/// A short-hand definition for a GreaterVerifier with a type check for `double` + +/** + * A short-hand definition for a GreaterVerifier with a type check for `double`. + */ using DoubleGreaterVerifier = GreaterVerifier; -/// A short-hand definition for a GreaterEqualVerifier with a type check for `int` + +/** + * A short-hand definition for a GreaterEqualVerifier with a type check for `int`. + */ using IntGreaterEqualVerifier = GreaterEqualVerifier; -/// A short-hand definition for a GreaterEqualVerifier with a type check for `double` + +/** + * A short-hand definition for a GreaterEqualVerifier with a type check for `double`. + */ using DoubleGreaterEqualVerifier = GreaterEqualVerifier; -/// A short-hand definition for a EqualVerifier with a type check for `bool` + +/** + * A short-hand definition for a EqualVerifier with a type check for `bool`. + */ using BoolEqualVerifier = EqualVerifier; -/// A short-hand definition for a EqualVerifier with a type check for `int` + +/** + * A short-hand definition for a EqualVerifier with a type check for `int`. + */ using IntEqualVerifier = EqualVerifier; -/// A short-hand definition for a EqualVerifier with a type check for `double` + +/** + * A short-hand definition for a EqualVerifier with a type check for `double`. + */ using DoubleEqualVerifier = EqualVerifier; -/// A short-hand definition for a EqualVerifier with a type check for `string` + +/** + * A short-hand definition for a EqualVerifier with a type check for `string`. + */ using StringEqualVerifier = EqualVerifier; -/// A short-hand definition for a UnequalVerifier with a type check for `bool` + +/** + * A short-hand definition for a UnequalVerifier with a type check for `bool`. + */ using BoolUnequalVerifier = UnequalVerifier; -/// A short-hand definition for a UnequalVerifier with a type check for `int` + +/** + * A short-hand definition for a UnequalVerifier with a type check for `int`. + */ using IntUnequalVerifier = UnequalVerifier; -/// A short-hand definition for a UnequalVerifier with a type check for `double` + +/** + * A short-hand definition for a UnequalVerifier with a type check for `double`. + */ using DoubleUnequalVerifier = UnequalVerifier; -/// A short-hand definition for a UnequalVerifier with a type check for `string` + +/** + * A short-hand definition for a UnequalVerifier with a type check for `string`. + */ using StringUnequalVerifier = UnequalVerifier; -/// A short-hand definition for a InListVerifier with a type check for `bool` +/** + * A short-hand definition for a InListVerifier with a type check for `bool`. + */ using BoolInListVerifier = InListVerifier; -/// A short-hand definition for a InListVerifier with a type check for `int` + +/** + * A short-hand definition for a InListVerifier with a type check for `int`. + */ using IntInListVerifier = InListVerifier; -/// A short-hand definition for a InListVerifier with a type check for `double` + +/** + * A short-hand definition for a InListVerifier with a type check for `double`. + */ using DoubleInListVerifier = InListVerifier; -/// A short-hand definition for a InListVerifier with a type check for `string` + +/** + * A short-hand definition for a InListVerifier with a type check for `string`. + */ using StringInListVerifier = InListVerifier; -/// A short-hand definition for a NotInListVerifier with a type check for `bool` + +/** + * A short-hand definition for a NotInListVerifier with a type check for `bool`. + */ using BoolNotInListVerifier = NotInListVerifier; -/// A short-hand definition for a NotInListVerifier with a type check for `int` + +/** + * A short-hand definition for a NotInListVerifier with a type check for `int`. + */ using IntNotInListVerifier = NotInListVerifier; -/// A short-hand definition for a NotInListVerifier with a type check for `double` + +/** + * A short-hand definition for a NotInListVerifier with a type check for `double`. + */ using DoubleNotInListVerifier = NotInListVerifier; -/// A short-hand definition for a NotInListVerifier with a type check for `string` + +/** + * A short-hand definition for a NotInListVerifier with a type check for `string`. + */ using StringNotInListVerifier = NotInListVerifier; -/// A short-hand definition for a InRangeVerifier with a type check for `int` +/** + * A short-hand definition for a InRangeVerifier with a type check for `int`. + */ using IntInRangeVerifier = InRangeVerifier; -/// A short-hand definition for a InRangeVerifier with a type check for `double` + +/** + * A short-hand definition for a InRangeVerifier with a type check for `double`. + */ using DoubleInRangeVerifier = InRangeVerifier; -/// A short-hand definition for a InRangeVerifier with a type check for `vec2` + +/** + * A short-hand definition for a InRangeVerifier with a type check for `vec2`. + */ using Vec2InRangeVerifier = InRangeVerifier; -/// A short-hand definition for a NotInRangeVerifier with a type check for `int` + +/** + * A short-hand definition for a NotInRangeVerifier with a type check for `int`. + */ using IntNotInRangeVerifier = NotInRangeVerifier; -/// A short-hand definition for a NotInRangeVerifier with a type check for `double` + +/** + * A short-hand definition for a NotInRangeVerifier with a type check for `double`. + */ using DoubleNotInRangeVerifier = NotInRangeVerifier; -/// A short-hand definition for a AnnotationVerifier with a type check for `bool` +/** + * A short-hand definition for a AnnotationVerifier with a type check for `bool`. + */ using BoolAnnotationVerifier = AnnotationVerifier; -/// A short-hand definition for a AnnotationVerifier with a type check for `int` + +/** + * A short-hand definition for a AnnotationVerifier with a type check for `int`. + */ using IntAnnotationVerifier = AnnotationVerifier; -/// A short-hand definition for a AnnotationVerifier with a type check for `double` + +/** + * A short-hand definition for a AnnotationVerifier with a type check for `double`. + */ using DoubleAnnotationVerifier = AnnotationVerifier; -/// A short-hand definition for a AnnotationVerifier with a type check for `string` + +/** + * A short-hand definition for a AnnotationVerifier with a type check for `string`. + */ using StringAnnotationVerifier = AnnotationVerifier; -/// A short-hand definition for a AnnotationVerifier with a type check for -/// `ghoul::Dictionary` + +/** + * A short-hand definition for a AnnotationVerifier with a type check for + * `ghoul::Dictionary` + */ using TableAnnotationVerifier = AnnotationVerifier; // Definitions of external templates that are instantiated in the cpp file diff --git a/include/openspace/engine/globalscallbacks.h b/include/openspace/engine/globalscallbacks.h index a0f606b65c..4dba55e44e 100644 --- a/include/openspace/engine/globalscallbacks.h +++ b/include/openspace/engine/globalscallbacks.h @@ -66,11 +66,10 @@ inline std::vector>* touchExit; /** * If the framerate becomes slow, Chromium Embedded Framework (used in Web Browser Module) * needs to perform its message loop work more frequently than once per frame. If this - * method is not called frequently enough, the GUI will become much less responsive. - * A future more long-term may decouple the browser's message work loop from the main - * render loop altogehter using a separate thread. - * Currently, this method is called from within the RenderEngine, - * between calls to individual renderables. + * method is not called frequently enough, the GUI will become much less responsive. A + * future more long-term may decouple the browser's message work loop from the main render + * loop altogehter using a separate thread. Currently, this method is called from within + * the RenderEngine, between calls to individual renderables. */ extern void (*webBrowserPerformanceHotfix)(); diff --git a/include/openspace/engine/logfactory.h b/include/openspace/engine/logfactory.h index 3216e44e32..e4cce1ba43 100644 --- a/include/openspace/engine/logfactory.h +++ b/include/openspace/engine/logfactory.h @@ -43,12 +43,14 @@ namespace documentation { struct Documentation; } * logfile should be created. Both logs can be customized using the `Append`, * `TimeStamping`, `DateStamping`, `CategoryStamping`, and `LogLevelStamping` values. * - * \param dictionary The dictionary from which the ghoul::logging::Log should be created + * \param dictionary The dictionary from which the ghoul::logging::Log should be created * \return The created ghoul::logging::Log - * \post The return value will not be `nullptr` - * \throw ghoul::RuntimeError If there was an error creating the ghoul::logging::Log - * \sa ghoul::logging::TextLog - * \sa ghoul::logging::HTMLLog + * + * \post The return value will not be `nullptr` + * \throw ghoul::RuntimeError If there was an error creating the ghoul::logging::Log + * + * \sa ghoul::logging::TextLog + * \sa ghoul::logging::HTMLLog */ std::unique_ptr createLog(const ghoul::Dictionary& dictionary); diff --git a/include/openspace/engine/moduleengine.h b/include/openspace/engine/moduleengine.h index 8a37586007..4bfe52c166 100644 --- a/include/openspace/engine/moduleengine.h +++ b/include/openspace/engine/moduleengine.h @@ -45,9 +45,9 @@ namespace scripting { struct LuaLibrary; } * The ModuleEngine is the central repository for registering and accessing * OpenSpaceModule for the current application run. By initializing (#initialize) the * ModuleEngine, the default set of OpenSpaceModule%s as generated by CMake in the - * `moduleregistration.h` file is automatically registered and created. - * Additional OpenSpaceModule%s can be registered with the #registerModule function, which - * will internally call the OpenSpaceModule::initialize method. + * `moduleregistration.h` file is automatically registered and created. Additional + * OpenSpaceModule%s can be registered with the #registerModule function, which will + * internally call the OpenSpaceModule::initialize method. */ class ModuleEngine : public properties::PropertyOwner { public: @@ -55,11 +55,10 @@ public: /** * Registers all of the OpenSpaceModule%s which are created by the CMake configuration - * and stored in the `moduleregistration.h` file. For all of those modules - * the OpenSpaceModule::initialize method with will called. + * and stored in the `moduleregistration.h` file. For all of those modules the + * OpenSpaceModule::initialize method with will called. * - * \throw ghoul::RuntimeError If two modules in the default modules have the same - * name + * \throw ghoul::RuntimeError If two modules in the default modules have the same name */ void initialize(const std::map& moduleConfigurations); @@ -104,7 +103,7 @@ public: * to have the public static member variable `name` which must be equal to * the name of the module used in its constructor. * - * \return a pointer to the module of the given subclass + * \return A pointer to the module of the given subclass */ template ModuleSubClass* module() const; @@ -118,9 +117,9 @@ public: ghoul::systemcapabilities::Version requiredOpenGLVersion() const; /** - * Returns the Lua library that contains all Lua functions available to affect the - * modules. - */ + * Returns the Lua library that contains all Lua functions available to affect the + * modules. + */ static scripting::LuaLibrary luaLibrary(); private: diff --git a/include/openspace/engine/openspaceengine.h b/include/openspace/engine/openspaceengine.h index 73a97a54e8..291a65aefa 100644 --- a/include/openspace/engine/openspaceengine.h +++ b/include/openspace/engine/openspaceengine.h @@ -51,15 +51,17 @@ class Scene; namespace scripting { struct LuaLibrary; } - // Structure that is responsible for the delayed shutdown of the application +/** + * Structure that is responsible for the delayed shutdown of the application. + */ struct ShutdownInformation { - // Whether the application is currently in shutdown mode (i.e. counting down the - // timer and closing it at '0' + /// Whether the application is currently in shutdown mode (i.e. counting down the + /// timer and closing it at '0' bool inShutdown = false; - // Total amount of time the application will wait before actually shutting down + /// Total amount of time the application will wait before actually shutting down float waitTime = 0.f; - // Current state of the countdown; if it reaches '0', the application will - // close + /// Current state of the countdown; if it reaches '0', the application will + /// close float timer = 0.f; }; @@ -73,9 +75,11 @@ struct CommandlineArguments { class OpenSpaceEngine : public properties::PropertyOwner { public: - // A mode that specifies which part of the system is currently in control. - // The mode can be used to limit certain features, like setting time, navigation - // or triggering scripts + /** + * A mode that specifies which part of the system is currently in control. The mode + * can be used to limit certain features, like setting time, navigation or triggering + * scripts. + */ enum class Mode { UserControl = 0, SessionRecordingPlayback, @@ -180,7 +184,8 @@ private: * Sets the camera position using the time contents of a profile. The function will * set an absolute position or a go-to-geolocation command using the globebrowsing * module. - * \param p The Profile to be read. + * + * \param p The Profile to be read */ void setCameraFromProfile(const Profile& p); @@ -188,21 +193,21 @@ void setCameraFromProfile(const Profile& p); * Reads a list of modules from a profile, and executes scripts based on whether or * not the corresponding module is loaded. * - * \param p The Profile to be read. + * \param p The Profile to be read */ void setModulesFromProfile(const Profile& p); /** * Registers actions from the contents of a profile. * - * \param p The Profile to be read. + * \param p The Profile to be read */ void setActionsFromProfile(const Profile& p); /** * Registers keybindings from the contents of a profile. * - * \param p The Profile to be read. + * \param p The Profile to be read */ void setKeybindingsFromProfile(const Profile& p); @@ -211,7 +216,7 @@ void setKeybindingsFromProfile(const Profile& p); * If any nodes are listed, a script to mark these will be queued with the * script engine. * - * \param p The Profile to be read. + * \param p The Profile to be read */ void setMarkInterestingNodesFromProfile(const Profile& p); @@ -220,7 +225,7 @@ void setMarkInterestingNodesFromProfile(const Profile& p); * at the end of the initialization. Any openspace lua commands are allowed, * and will be added to the script queue. * - * \param p The Profile to be read. + * \param p The Profile to be read */ void setAdditionalScriptsFromProfile(const Profile& p); diff --git a/include/openspace/engine/syncengine.h b/include/openspace/engine/syncengine.h index 1b5107d4ba..fb6d9933f2 100644 --- a/include/openspace/engine/syncengine.h +++ b/include/openspace/engine/syncengine.h @@ -36,72 +36,71 @@ namespace openspace { class Syncable; /** - * Manages a collection of `Syncable`s and ensures they are synchronized - * over SGCT nodes. Encoding/Decoding order is handles internally. + * Manages a collection of `Syncable`s and ensures they are synchronized over SGCT nodes. + * Encoding/Decoding order is handles internally. */ class SyncEngine { public: BooleanType(IsMaster); /** - * Creates a new SyncEngine which a buffer size of \p syncBufferSize + * Creates a new SyncEngine which a buffer size of \p syncBufferSize. + * * \pre syncBufferSize must be bigger than 0 */ SyncEngine(unsigned int syncBufferSize); /** - * Encodes all added Syncables in the injected `SyncBuffer`. - * This method is only called on the SGCT master node + * Encodes all added Syncables in the injected `SyncBuffer`. This method is only + * called on the SGCT master node. */ std::vector encodeSyncables(); /** - * Decodes the `SyncBuffer` into the added Syncables. - * This method is only called on the SGCT client nodes + * Decodes the `SyncBuffer` into the added Syncables. This method is only called on + * the SGCT client nodes. */ void decodeSyncables(std::vector data); /** - * Invokes the presync method of all added Syncables + * Invokes the presync method of all added Syncables. */ void preSynchronization(IsMaster isMaster); /** - * Invokes the postsync method of all added Syncables + * Invokes the postsync method of all added Syncables. */ void postSynchronization(IsMaster isMaster); /** * Add a Syncable to be synchronized over the SGCT cluster. - * \pre syncable must not be nullptr + * + * \pre syncable must not be `nullptr` */ void addSyncable(Syncable* syncable); /** - * Add multiple Syncables to be synchronized over the SGCT cluster + * Add multiple Syncables to be synchronized over the SGCT cluster. + * * \pre syncables must not contain any nullptr */ void addSyncables(const std::vector& syncables); /** - * Remove a Syncable from being synchronized over the SGCT cluster + * Remove a Syncable from being synchronized over the SGCT cluster. */ void removeSyncable(Syncable* syncable); /** - * Remove multiple Syncables from being synchronized over the SGCT cluster + * Remove multiple Syncables from being synchronized over the SGCT cluster. */ void removeSyncables(const std::vector& syncables); private: - /** - * Vector of Syncables. The vectors ensures consistent encode/decode order - */ + /// Vector of Syncables. The vectors ensures consistent encode/decode order. std::vector _syncables; - /** - * Databuffer used in encoding/decoding - */ + /// Databuffer used in encoding/decoding SyncBuffer _syncBuffer; }; diff --git a/include/openspace/events/event.h b/include/openspace/events/event.h index 08f15512d9..9f2f344bae 100644 --- a/include/openspace/events/event.h +++ b/include/openspace/events/event.h @@ -111,7 +111,7 @@ void logAllEvents(const Event* e); // /** - * This event is created whenever a new scene graph node is added to the system. By the + * This event is created whenever a new scene graph node is added to the system. By the * time this event is signalled, the scene graph node has already been created and added * to the scene. */ @@ -130,7 +130,7 @@ struct EventSceneGraphNodeAdded : public Event { }; /** - * This event is created whenever a scene graph node was removed. By the time this event + * This event is created whenever a scene graph node was removed. By the time this event * is signalled, the scene graph node has already been removed. */ struct EventSceneGraphNodeRemoved : public Event { @@ -164,7 +164,7 @@ struct EventParallelConnection : public Event { /** * Creates an instance of an EventParallelConnection event. * - * \param state_ The new state of the parallel connection system; is one of + * \param state_ The new state of the parallel connection system; is one of * `Established`, `Lost`, `HostshipGained`, or `HostshipLost` */ explicit EventParallelConnection(State state_); @@ -201,8 +201,8 @@ struct EventApplicationShutdown : public Event { /** * Creates an instance of an EventApplicationShutdown event. * - * \param state_ The next state of the application shutdown sequence; is one of - * `Started`, `Aborted`, or `Finished` + * \param state_ The next state of the application shutdown sequence; is one of + * `Started`, `Aborted`, or `Finished` */ explicit EventApplicationShutdown(State state_); const State state; @@ -210,7 +210,7 @@ struct EventApplicationShutdown : public Event { /** * This event is created when a new screenspace renderable has been created. By the time - * this event is craeted, the screenspace renderable is already registered and available. + * this event is created, the screenspace renderable is already registered and available. */ struct EventScreenSpaceRenderableAdded : public Event { static constexpr Type Type = Event::Type::ScreenSpaceRenderableAdded; @@ -229,7 +229,7 @@ struct EventScreenSpaceRenderableAdded : public Event { /** * This event is created when a screenspace renderable has been removed from the system. * When this event is created, the screenspace renderable has already been removed and is - * no longer available + * no longer available. */ struct EventScreenSpaceRenderableRemoved : public Event { static constexpr Type Type = Event::Type::ScreenSpaceRenderableRemoved; @@ -248,18 +248,18 @@ struct EventScreenSpaceRenderableRemoved : public Event { * distances. Right now, only movement relative to camera's focus node is considered. * Each scene graph node has an interaction sphere radius that serves as the reference * distance for all spheres. -``` -Diagram of events for a camera moving from right-to-left. Interaction sphere is 'O' in -middle, and ')' are spherical boundaries. The approach factor, reach factor, and -interaction sphere radius are all taken from the current focus node. - -|<------------------->| Approach factor * Interaction sphere - |<------>| Reach Factor * Interaction sphere - -( ( O ) ) -^ ^ ^ ^ -Exiting Receding Reaching Approaching -``` + * ``` + * Diagram of events for a camera moving from right-to-left. Interaction sphere is 'O' in + * middle, and ')' are spherical boundaries. The approach factor, reach factor, and + * interaction sphere radius are all taken from the current focus node. + * + * |<------------------->| Approach factor * Interaction sphere + * |<------>| Reach Factor * Interaction sphere + * + * ( ( O ) ) + * ^ ^ ^ ^ + * Exiting Receding Reaching Approaching + * ``` */ struct EventCameraFocusTransition : public Event { static constexpr Type Type = Event::Type::CameraFocusTransition; @@ -347,7 +347,7 @@ struct EventPlanetEclipsed : public Event { /** * This event is created when the interpolation of a property value is finished. If the - * interpolation time of a property change is 0s, this event is not fired + * interpolation time of a property change is 0s, this event is not fired. */ struct EventInterpolationFinished : public Event { static constexpr Type Type = Event::Type::InterpolationFinished; @@ -562,7 +562,7 @@ struct EventCameraPathFinished : public Event { }; /** - * This event is created when the a camera moves location + * This event is created when the a camera moves location. */ struct EventCameraMovedPosition : public Event { static constexpr Type Type = Event::Type::CameraMovedPosition; diff --git a/include/openspace/events/eventengine.h b/include/openspace/events/eventengine.h index 212a0305af..b0a84b79c3 100644 --- a/include/openspace/events/eventengine.h +++ b/include/openspace/events/eventengine.h @@ -48,7 +48,7 @@ public: * This function returns the first event stored in the EventEngine, or `nullptr` if * no event exists. To navigate the full list of events, you can access the returned * Event's next function. If the end of the list is reached, the next pointer will be - * a nullptr + * a `nullptr`. * * \return The first event stored in the EventEngine or nullptr if no event exists */ @@ -57,11 +57,11 @@ public: /** * Publish a new event of type T by providing optional arguments Args to the Event's * constructor. An example of usage is - * `engine.publishEvent("a", 2.0);` which would call the - * constructor of `MyEvent` with a `const char*` and `double` parameter. + * `engine.publishEvent("a", 2.0);` which would call the constructor of + * `MyEvent` with a `const char*` and `double` parameter. * - * \param args The arguments that are passed to the constructor of T * \tparam T The subclass of Event that is to be published + * \param args The arguments that are passed to the constructor of T */ template void publishEvent(Args&&... args); @@ -101,7 +101,7 @@ public: /** * Removing registration for a specific event identified by the \p identifier. * - * \param identifier The unique identifier of the event that should be removed. + * \param identifier The unique identifier of the event that should be removed */ void unregisterEventAction(uint32_t identifier); @@ -130,7 +130,7 @@ public: /** * Triggers all actions that are registered for events that are in the current event - * queue + * queue. */ void triggerActions() const; @@ -144,10 +144,9 @@ private: /// The last event in the chain of events stored in the memory pool events::Event* _lastEvent = nullptr; - - // The type is duplicated in the ActionInfo as well, but we want it in the ActionInfo - // to be able to return them to a caller and we want it in this unordered_map to make - // the lookup really fast. So having this extra wasted memory is probably worth it + /// The type is duplicated in the ActionInfo as well, but we want it in the ActionInfo + /// to be able to return them to a caller and we want it in this unordered_map to make + /// the lookup really fast. So having this extra wasted memory is probably worth it std::unordered_map> _eventActions; static uint32_t nextRegisteredEventId; diff --git a/include/openspace/interaction/camerainteractionstates.h b/include/openspace/interaction/camerainteractionstates.h index b220db6115..5e31c37c5f 100644 --- a/include/openspace/interaction/camerainteractionstates.h +++ b/include/openspace/interaction/camerainteractionstates.h @@ -33,9 +33,9 @@ namespace openspace::interaction { class CameraInteractionStates { public: /** - * \param sensitivity - * \param velocityScaleFactor can be set to 60 to remove the inertia of the - * interaction. Lower value will make it harder to move the camera. + * \param sensitivity Interaction sensitivity + * \param velocityScaleFactor Can be set to 60 to remove the inertia of the + * interaction. Lower value will make it harder to move the camera */ CameraInteractionStates(double sensitivity, double velocityScaleFactor); virtual ~CameraInteractionStates() = default; @@ -54,9 +54,9 @@ public: void resetVelocities(); - /* - * Returns true if any of the velocities are larger than zero, - * i.e. wether an interaction happened + /** + * Returns true if any of the velocities are larger than zero, i.e. wether an + * interaction happened. */ bool hasNonZeroVelocities(bool checkOnlyMovement = false); diff --git a/include/openspace/interaction/delayedvariable.h b/include/openspace/interaction/delayedvariable.h index 7f71c8f13b..67046c7bdf 100644 --- a/include/openspace/interaction/delayedvariable.h +++ b/include/openspace/interaction/delayedvariable.h @@ -28,9 +28,9 @@ namespace openspace::interaction { /** - * Class that acts as a smoothing filter to a variable. The filter has a step - * response on a form that resembles the function y = 1-e^(-t/scale). The variable - * will be updated as soon as it is set to a value (calling the set() function). + * Class that acts as a smoothing filter to a variable. The filter has a step response on + * a form that resembles the function y = 1-e^(-t/scale). The variable will be updated as + * soon as it is set to a value (calling the set() function). */ template class DelayedVariable { diff --git a/include/openspace/interaction/interactionmonitor.h b/include/openspace/interaction/interactionmonitor.h index 9cd80e210d..6cc2907a0e 100644 --- a/include/openspace/interaction/interactionmonitor.h +++ b/include/openspace/interaction/interactionmonitor.h @@ -52,7 +52,7 @@ public: /* * Called from all places we want to mark activity from. Updates the last registered - * interaction time + * interaction time. */ void markInteraction(); diff --git a/include/openspace/interaction/interpolator.h b/include/openspace/interaction/interpolator.h index 867b63ab66..d017bd8618 100644 --- a/include/openspace/interaction/interpolator.h +++ b/include/openspace/interaction/interpolator.h @@ -29,7 +29,7 @@ namespace openspace::interaction { -/* +/** * Interpolates a typename T using a transfer function. */ template diff --git a/include/openspace/interaction/joystickinputstate.h b/include/openspace/interaction/joystickinputstate.h index 76f68ff437..6c9cd42fa0 100644 --- a/include/openspace/interaction/joystickinputstate.h +++ b/include/openspace/interaction/joystickinputstate.h @@ -37,7 +37,7 @@ namespace openspace::interaction { /** * Actions that any button of a joystick can have. Each button must be in one of these - * states + * states. */ enum class JoystickAction : uint8_t { /// Idle state if the button is unpressed and has been unpressed since last frame @@ -81,7 +81,7 @@ struct JoystickInputStates : public std::array static constexpr int MaxNumJoysticks = 16; /** - * This function return the number of axes the joystick with the given name has + * This function return the number of axes the joystick with the given name has. * * \param joystickName The name of the joystick to check how many axes it has, * if empty the max number of axes for all joysticks are returned @@ -90,7 +90,7 @@ struct JoystickInputStates : public std::array int numAxes(const std::string& joystickName = "") const; /** - * This function return the number of buttons the joystick with the given name has + * This function return the number of buttons the joystick with the given name has. * * \param joystickName The name of the joystick to check how many buttons it has, * if empty the max number of buttons for all joysticks are returned diff --git a/include/openspace/interaction/sessionrecording.h b/include/openspace/interaction/sessionrecording.h index 0741e4e6f6..284ea1e459 100644 --- a/include/openspace/interaction/sessionrecording.h +++ b/include/openspace/interaction/sessionrecording.h @@ -72,9 +72,9 @@ public: double timeSim; }; - /* - * Struct for storing a script substring that, if found in a saved script, - * will be replaced by its substringReplacement counterpart. + /** + * Struct for storing a script substring that, if found in a saved script, will be + * replaced by its substringReplacement counterpart. */ struct ScriptSubstringReplace { std::string substringFound; @@ -110,9 +110,9 @@ public: void deinitialize(); /** - * This is called with every rendered frame. If in recording state, the camera - * state will be saved to the recording file (if its state has changed since last). - * If in playback state, the next keyframe will be used (if it is time to do so). + * This is called with every rendered frame. If in recording state, the camera state + * will be saved to the recording file (if its state has changed since last). If in + * playback state, the next keyframe will be used (if it is time to do so). */ void preSynchronization(); @@ -123,12 +123,12 @@ public: void render(); /** - * Current time based on playback mode + * Current time based on playback mode. */ double currentTime() const; /** - * Fixed delta time set by user for use during saving of frame during playback mode + * Fixed delta time set by user for use during saving of frame during playback mode. */ double fixedDeltaTimeDuringFrameOutput() const; @@ -140,9 +140,8 @@ public: * However, during playback it is incremented by the fixed framerate of the playback * rather than the actual clock value (as in normal operation). * - * \returns number of microseconds elapsed since playback started in terms of the - * number of rendered frames multiplied by the fixed time increment per - * frame + * \return Number of microseconds elapsed since playback started in terms of the + * number of rendered frames multiplied by the fixed time increment per frame */ std::chrono::steady_clock::time_point currentPlaybackInterpolationTime() const; @@ -151,28 +150,27 @@ public: * used when playback is set to be in the mode where a screenshot is captured with * every rendered frame (enableTakeScreenShotDuringPlayback() is used to enable this * mode). At the start of playback, this timer is set to the value of the current - * applicationTime function provided by the window delegate (used during normal - * mode or playback). However, during playback it is incremented by the fixed - * framerate of the playback rather than the actual clock value. + * applicationTime function provided by the window delegate (used during normal mode + * or playback). However, during playback it is incremented by the fixed framerate of + * the playback rather than the actual clock value. * - * \returns application time in seconds, for use in playback-with-frames mode + * \return Application time in seconds, for use in playback-with-frames mode */ double currentApplicationInterpolationTime() const; /** - * Starts a recording session, which will save data to the provided filename - * according to the data format specified, and will continue until recording is - * stopped using stopRecording() method. + * Starts a recording session, which will save data to the provided filename according + * to the data format specified, and will continue until recording is stopped using + * stopRecording() method. * - * \param filename file saved with recorded keyframes. - * - * \returns true if recording to file starts without errors. + * \param filename File saved with recorded keyframes + * \return `true` if recording to file starts without errors */ bool startRecording(const std::string& filename); /** - * Starts a recording session, which will save data to the provided filename - * in ASCII data format until recording is stopped using stopRecording() method. + * Starts a recording session, which will save data to the provided filename in ASCII + * data format until recording is stopped using stopRecording() method. * * \param dataMode The format in which the session recording is stored */ @@ -187,23 +185,23 @@ public: /** * Used to check if a session recording is in progress. * - * \return true if recording is in progress + * \return `true` if recording is in progress */ bool isRecording() const; /** * Starts a playback session, which can run in one of three different time modes. * - * \param filename file containing recorded keyframes to play back. The file path - * is relative to the base recordings directory specified in the - * config file by the RECORDINGS variable - * \param timeMode which of the 3 time modes to use for time reference during - * \param forceSimTimeAtStart if true simulation time is forced to that of playback + * \param filename File containing recorded keyframes to play back. The file path is + * relative to the base recordings directory specified in the config + * file by the RECORDINGS variable + * \param timeMode Which of the 3 time modes to use for time reference during + * \param forceSimTimeAtStart If true simulation time is forced to that of playback * playback: recorded time, application time, or simulation time. See the * LuaLibrary entry for SessionRecording for details on these time modes - * \param loop if true then the file will playback in loop mode, continuously - * looping back to the beginning until it is manually stopped - * \param shouldWaitForFinishedTiles if true, the playback will wait for tiles to be + * \param loop If true then the file will playback in loop mode, continuously looping + * back to the beginning until it is manually stopped + * \param shouldWaitForFinishedTiles If true, the playback will wait for tiles to be * finished before progressing to the next frame. This value is only used when * `enableTakeScreenShotDuringPlayback` was called before. Otherwise this value * will be ignored @@ -214,8 +212,8 @@ public: bool forceSimTimeAtStart, bool loop, bool shouldWaitForFinishedTiles); /** - * Used to stop a playback in progress. If open, the playback file will be closed, - * and all keyframes deleted from memory. + * Used to stop a playback in progress. If open, the playback file will be closed, and + * all keyframes deleted from memory. */ void stopPlayback(); @@ -227,33 +225,34 @@ public: bool isPlaybackPaused(); /** - * Pauses a playback session. This does both the normal pause functionality of - * setting simulation delta time to zero, and pausing the progression through the - * timeline. + * Pauses a playback session. This does both the normal pause functionality of setting + * simulation delta time to zero, and pausing the progression through the timeline. * - * \param pause if true, then will set playback timeline progression to zero + * \param pause If `true`, then will set playback timeline progression to zero */ void setPlaybackPause(bool pause); /** - * Enables that rendered frames should be saved during playback + * Enables that rendered frames should be saved during playback. + * * \param fps Number of frames per second. */ void enableTakeScreenShotDuringPlayback(int fps); /** - * Used to disable that renderings are saved during playback + * Used to disable that renderings are saved during playback. */ void disableTakeScreenShotDuringPlayback(); /** * Used to check if a session playback is in progress. - * \returns true if playback is in progress. + * + * \return `true` if playback is in progress */ bool isPlayingBack() const; /** - * Is saving frames during playback + * Is saving frames during playback. */ bool isSavingFramesDuringPlayback() const; @@ -289,15 +288,14 @@ public: /** * \return The Lua library that contains all Lua functions available to affect the - * interaction + * interaction */ static openspace::scripting::LuaLibrary luaLibrary(); /** * Used to request a callback for notification of playback state change. * - * \param cb function handle for callback - * + * \param cb Function handle for callback * \return CallbackHandle value of callback number */ CallbackHandle addStateChangeCallback(StateChangeCallback cb); @@ -305,14 +303,14 @@ public: /** * Removes the callback for notification of playback state change. * - * \param callback function handle for the callback + * \param callback Function handle for the callback */ void removeStateChangeCallback(CallbackHandle callback); /** * Provides list of available playback files. * - * \return vector of filenames in recordings dir + * \return Vector of filenames in recordings dir */ std::vector playbackList() const; @@ -320,12 +318,11 @@ public: * Reads a camera keyframe from a binary format playback file, and populates input * references with the parameters of the keyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a camera keyframe which contains camera details - * \param file an ifstream reference to the playback file being read - * \param lineN keyframe number in playback file where this keyframe resides - * - * \return true if data read has no errors + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a camera keyframe which contains camera details + * \param file An ifstream reference to the playback file being read + * \param lineN Keyframe number in playback file where this keyframe resides + * \return `true` if data read has no errors */ bool readCameraKeyframeBinary(Timestamps& times, datamessagestructures::CameraKeyframe& kf, std::ifstream& file, int lineN); @@ -334,12 +331,11 @@ public: * Reads a camera keyframe from an ascii format playback file, and populates input * references with the parameters of the keyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a camera keyframe which contains camera details - * \param currentParsingLine string containing the most current line that was read - * \param lineN line number in playback file where this keyframe resides - * - * \return true if data read has no errors + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a camera keyframe which contains camera details + * \param currentParsingLine String containing the most current line that was read + * \param lineN Line number in playback file where this keyframe resides + * \return `true` if data read has no errors */ bool readCameraKeyframeAscii(Timestamps& times, datamessagestructures::CameraKeyframe& kf, std::string currentParsingLine, @@ -349,12 +345,11 @@ public: * Reads a time keyframe from a binary format playback file, and populates input * references with the parameters of the keyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a time keyframe which contains time details - * \param file an ifstream reference to the playback file being read - * \param lineN keyframe number in playback file where this keyframe resides - * - * \return true if data read has no errors + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a time keyframe which contains time details + * \param file An ifstream reference to the playback file being read + * \param lineN Keyframe number in playback file where this keyframe resides + * \return `true` if data read has no errors */ bool readTimeKeyframeBinary(Timestamps& times, datamessagestructures::TimeKeyframe& kf, std::ifstream& file, int lineN); @@ -363,12 +358,11 @@ public: * Reads a time keyframe from an ascii format playback file, and populates input * references with the parameters of the keyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a time keyframe which contains time details - * \param currentParsingLine string containing the most current line that was read - * \param lineN line number in playback file where this keyframe resides - * - * \return true if data read has no errors + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a time keyframe which contains time details + * \param currentParsingLine String containing the most current line that was read + * \param lineN Line number in playback file where this keyframe resides + * \return `true` if data read has no errors */ bool readTimeKeyframeAscii(Timestamps& times, datamessagestructures::TimeKeyframe& kf, std::string currentParsingLine, @@ -378,13 +372,12 @@ public: * Reads a script keyframe from a binary format playback file, and populates input * references with the parameters of the keyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a script keyframe which contains the size of the script - * (in chars) and the text itself - * \param file an ifstream reference to the playback file being read - * \param lineN keyframe number in playback file where this keyframe resides - * - * \return true if data read has no errors + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a script keyframe which contains the size of the script (in + * chars) and the text itself + * \param file An ifstream reference to the playback file being read + * \param lineN Keyframe number in playback file where this keyframe resides + * \return `true` if data read has no errors */ bool readScriptKeyframeBinary(Timestamps& times, datamessagestructures::ScriptMessage& kf, std::ifstream& file, int lineN); @@ -393,36 +386,35 @@ public: * Reads a script keyframe from an ascii format playback file, and populates input * references with the parameters of the keyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a script keyframe which contains the size of the script - * (in chars) and the text itself - * \param currentParsingLine string containing the most current line that was read - * \param lineN line number in playback file where this keyframe resides - * - * \return true if data read has no errors + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a script keyframe which contains the size of the script (in + * chars) and the text itself + * \param currentParsingLine String containing the most current line that was read + * \param lineN Line number in playback file where this keyframe resides + * \return `true` if data read has no errors */ bool readScriptKeyframeAscii(Timestamps& times, datamessagestructures::ScriptMessage& kf, std::string currentParsingLine, int lineN); /** - * Writes a camera keyframe to a binary format recording file using a CameraKeyframe + * Writes a camera keyframe to a binary format recording file using a CameraKeyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a camera keyframe which contains the camera details - * \param kfBuffer a buffer temporarily used for preparing data to be written - * \param file an ofstream reference to the recording file being written-to + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a camera keyframe which contains the camera details + * \param kfBuffer A buffer temporarily used for preparing data to be written + * \param file An ofstream reference to the recording file being written-to */ void saveCameraKeyframeBinary(Timestamps& times, datamessagestructures::CameraKeyframe& kf, unsigned char* kfBuffer, std::ofstream& file); /** - * Writes a camera keyframe to an ascii format recording file using a CameraKeyframe + * Writes a camera keyframe to an ascii format recording file using a CameraKeyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a camera keyframe which contains the camera details - * \param file an ofstream reference to the recording file being written-to + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a camera keyframe which contains the camera details + * \param file An ofstream reference to the recording file being written-to */ void saveCameraKeyframeAscii(Timestamps& times, datamessagestructures::CameraKeyframe& kf, std::ofstream& file); @@ -430,113 +422,111 @@ public: /** * Writes a time keyframe to a binary format recording file using a TimeKeyframe * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a time keyframe which contains the time details - * \param kfBuffer a buffer temporarily used for preparing data to be written - * \param file an ofstream reference to the recording file being written-to + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a time keyframe which contains the time details + * \param kfBuffer A buffer temporarily used for preparing data to be written + * \param file An ofstream reference to the recording file being written-to */ void saveTimeKeyframeBinary(Timestamps& times, datamessagestructures::TimeKeyframe& kf, unsigned char* kfBuffer, std::ofstream& file); /** - * Writes a time keyframe to an ascii format recording file using a TimeKeyframe + * Writes a time keyframe to an ascii format recording file using a TimeKeyframe. * - * \param times reference to a timestamps structure which contains recorded times - * \param kf reference to a time keyframe which contains the time details - * \param file an ofstream reference to the recording file being written-to + * \param times Reference to a timestamps structure which contains recorded times + * \param kf Reference to a time keyframe which contains the time details + * \param file An ofstream reference to the recording file being written-to */ void saveTimeKeyframeAscii(Timestamps& times, datamessagestructures::TimeKeyframe& kf, std::ofstream& file); /** - * Writes a script keyframe to a binary format recording file using a ScriptMessage + * Writes a script keyframe to a binary format recording file using a ScriptMessage. * - * \param times reference to a timestamps structure which contains recorded times - * \param sm reference to a ScriptMessage object which contains the script details - * \param smBuffer a buffer temporarily used for preparing data to be written - * \param file an ofstream reference to the recording file being written-to + * \param times Reference to a timestamps structure which contains recorded times + * \param sm Reference to a ScriptMessage object which contains the script details + * \param smBuffer A buffer temporarily used for preparing data to be written + * \param file An ofstream reference to the recording file being written-to */ void saveScriptKeyframeBinary(Timestamps& times, datamessagestructures::ScriptMessage& sm, unsigned char* smBuffer, std::ofstream& file); /** - * Writes a script keyframe to an ascii format recording file using a ScriptMessage + * Writes a script keyframe to an ascii format recording file using a ScriptMessage. * - * \param times reference to a timestamps structure which contains recorded times - * \param sm reference to a ScriptMessage which contains the script details - * \param file an ofstream reference to the recording file being written-to + * \param times Reference to a timestamps structure which contains recorded times + * \param sm Reference to a ScriptMessage which contains the script details + * \param file An ofstream reference to the recording file being written-to */ void saveScriptKeyframeAscii(Timestamps& times, datamessagestructures::ScriptMessage& sm, std::ofstream& file); /** * Since session recordings only record changes, the initial conditions aren't - * preserved when a playback starts. This function is called whenever a property - * value is set and a recording is in progress. Before the set happens, this - * function will read the current value of the property and store it so that when - * the recording is finished, the initial state will be added as a set property - * command at the beginning of the recording file, to be applied when playback - * starts. + * preserved when a playback starts. This function is called whenever a property value + * is set and a recording is in progress. Before the set happens, this function will + * read the current value of the property and store it so that when the recording is + * finished, the initial state will be added as a set property command at the + * beginning of the recording file, to be applied when playback starts. * * \param prop The property being set */ void savePropertyBaseline(properties::Property& prop); /** - * Reads header information from a session recording file + * Reads header information from a session recording file. * - * \param stream reference to ifstream that contains the session recording file data - * \param readLen_chars number of characters to be read, which may be the expected + * \param stream Reference to ifstream that contains the session recording file data + * \param readLen_chars Number of characters to be read, which may be the expected * length of the header line, or an arbitrary number of characters within it */ static std::string readHeaderElement(std::ifstream& stream, size_t readLen_chars); /** - * Reads header information from a session recording file + * Reads header information from a session recording file. * - * \param stream reference to ifstream that contains the session recording file - * data - * \param readLen_chars number of characters to be read, which may be the expected + * \param stream Reference to ifstream that contains the session recording file data + * \param readLen_chars Number of characters to be read, which may be the expected * length of the header line, or an arbitrary number of characters within it */ static std::string readHeaderElement(std::stringstream& stream, size_t readLen_chars); /** - * Writes a header to a binary recording file buffer + * Writes a header to a binary recording file buffer. * - * \param times reference to a timestamps structure which contains recorded times - * \param type single character signifying the keyframe type - * \param kfBuffer the char buffer holding the recording info to be written - * \param idx index into write buffer (this is updated with the num of chars written) + * \param times Reference to a timestamps structure which contains recorded times + * \param type Single character signifying the keyframe type + * \param kfBuffer The char buffer holding the recording info to be written + * \param idx Index into write buffer (this is updated with the num of chars written) */ static void saveHeaderBinary(Timestamps& times, char type, unsigned char* kfBuffer, size_t& idx); /** - * Writes a header to an ascii recording file buffer + * Writes a header to an ASCII recording file buffer. * - * \param times reference to a timestamps structure which contains recorded times - * \param type string signifying the keyframe type - * \param line the stringstream buffer being written to + * \param times Reference to a timestamps structure which contains recorded times + * \param type String signifying the keyframe type + * \param line The stringstream buffer being written to */ static void saveHeaderAscii(Timestamps& times, const std::string& type, std::stringstream& line); /** - * Saves a keyframe to an ascii recording file + * Saves a keyframe to an ASCII recording file. * - * \param entry the ascii string version of the keyframe (any type) - * \param file ofstream object to write to + * \param entry The ASCII string version of the keyframe (any type) + * \param file `std::ofstream` object to write to */ static void saveKeyframeToFile(std::string entry, std::ofstream& file); /** - * Checks if a specified recording file ends with a particular file extension + * Checks if a specified recording file ends with a particular file extension. * - * \param filename the name of the file to record to - * \param extension the file extension to check for + * \param filename The name of the file to record to + * \param extension The file extension to check for */ static bool hasFileExtension(std::string filename, std::string extension); @@ -545,10 +535,9 @@ public: * (will determine the file format conversion to convert from based on the file's * header version number). * - * \param filename name of the file to convert + * \param filename Name of the file to convert * \param depth iteration number to prevent runaway recursion (init call with zero) - * - * \return string containing the filename of the previous conversion step. This is + * \return String containing the filename of the previous conversion step. This is * used if there are multiple conversion steps where each step has to use * the output of the previous. */ @@ -558,43 +547,42 @@ public: * Converts file format of a session recording file to the current format version * (will determine the file format conversion to convert from based on the file's * header version number). Accepts a relative path (currently from task runner dir) - * rather than a path assumed to be relative to ${RECORDINGS}. + * rather than a path assumed to be relative to `${RECORDINGS}`. * * \param filenameRelative name of the file to convert */ void convertFileRelativePath(std::string filenameRelative); /** - * Goes to legacy session recording inherited class, and calls its convertFile() + * Goes to legacy session recording inherited class, and calls its #convertFile * method, and then returns the resulting conversion filename. * - * \param filename name of the file to convert - * \param depth iteration number to prevent runaway recursion (init call with zero) - * + * \param filename Name of the file to convert + * \param depth Iteration number to prevent runaway recursion (init call with zero) * \return string containing the filename of the conversion */ virtual std::string getLegacyConversionResult(std::string filename, int depth); - /* - * Version string for file format version currently supported by this class + /** + * Version string for file format version currently supported by this class. * * \return string of the file format version this class supports */ virtual std::string fileFormatVersion(); - /* - * Version string for file format version that a conversion operation will convert - * to (e.g. upgrades to this version). This is only relevant for inherited classes - * that support conversion from legacy versions (if called in the base class, it - * will return its own current version). + /** + * Version string for file format version that a conversion operation will convert to + * (e.g. upgrades to this version). This is only relevant for inherited classes that + * support conversion from legacy versions (if called in the base class, it will + * return its own current version). * * \return string of the file format version this class supports */ virtual std::string targetFileFormatVersion(); - /* - * Determines a filename for the conversion result based on the original filename - * and the file format version number. + /** + * Determines a filename for the conversion result based on the original filename and + the file format version number. * * \param filename source filename to be converted * @@ -776,6 +764,7 @@ protected: "NavigationHandler.OrbitalNavigator.RetargetAnchor", "NavigationHandler.OrbitalNavigator.RetargetAim" }; + //A script that begins with an exact match of any of the strings contained in // _scriptRejects will not be recorded const std::vector _scriptRejects = { @@ -791,12 +780,14 @@ protected: "Anchor", "Aim" }; + //Any script snippet included in this vector will be trimmed from any script // from the script manager, before it is recorded in the session recording file. // The remainder of the script will be retained. const std::vector _scriptsToBeTrimmed = { "openspace.sessionRecording.togglePlaybackPause" }; + //Any script snippet included in this vector will be trimmed from any script // from the script manager, before it is recorded in the session recording file. // The remainder of the script will be retained. diff --git a/include/openspace/interaction/websocketinputstate.h b/include/openspace/interaction/websocketinputstate.h index af010226e7..0b57864a23 100644 --- a/include/openspace/interaction/websocketinputstate.h +++ b/include/openspace/interaction/websocketinputstate.h @@ -37,7 +37,7 @@ namespace openspace::interaction { /** * Actions that any button of a websocket can have. Each button must be in one of these - * states + * states. */ enum class WebsocketAction : uint8_t { /// Idle state if the button is unpressed and has been unpressed since last frame diff --git a/include/openspace/mission/mission.h b/include/openspace/mission/mission.h index 281fe107ae..731e1951a3 100644 --- a/include/openspace/mission/mission.h +++ b/include/openspace/mission/mission.h @@ -51,8 +51,8 @@ struct Milestone { * phases within phases. Designed for WORM usage (Write Once, Read Multiple), and, * therefore, has only accessors. * - * Each MissionPhase is characterized by its MissionPhase::name, a TimeRange, an - * optional MissionPhase::description, and optional subphases. + * Each MissionPhase is characterized by its MissionPhase::name, a TimeRange, an optional + * MissionPhase::description, and optional subphases. */ class MissionPhase { public: @@ -147,6 +147,7 @@ public: /** * Returns the Documentation that describes the ghoul::Dictionarty that this * MissionPhase can be constructed from. + * * \return The Documentation that describes the required structure for a Dictionary */ static documentation::Documentation Documentation(); @@ -161,7 +162,7 @@ protected: * \param trace The list of MissionPhase%s that are active during the time \p time * \param maxDepth The maximum depth of levels that will be considered * - * \pre maxDepth must not be negative + * \pre \p maxDepth must not be negative */ void phaseTrace(double time, Trace& trace, int maxDepth) const; diff --git a/include/openspace/mission/missionmanager.h b/include/openspace/mission/missionmanager.h index 6e7d395b34..e7a3f9f1bc 100644 --- a/include/openspace/mission/missionmanager.h +++ b/include/openspace/mission/missionmanager.h @@ -78,18 +78,18 @@ public: * Sets the mission with the name \p missionName as the current mission. The current * mission is what is return by `currentMission()`. * - * \pre missionName must not be empty + * \pre \p missionName must not be empty */ void setCurrentMission(const std::string& missionName); /** - * Returns true if a current mission exists + * Returns true if a current mission exists. */ bool hasCurrentMission() const; /** - * Returns the latest mission specified to `setCurrentMission()`. If no mission has - * been specified, the first mission loaded will be returned. If no mission has been + * Returns the latest mission specified to #setCurrentMission. If no mission has been + * specified, the first mission loaded will be returned. If no mission has been * loaded, a warning will be printed and a dummy mission will be returned. */ const Mission& currentMission(); @@ -99,7 +99,6 @@ public: */ const std::map& missionMap(); - static scripting::LuaLibrary luaLibrary(); private: diff --git a/include/openspace/navigation/keyframenavigator.h b/include/openspace/navigation/keyframenavigator.h index e38fba0bfb..9bb1a3ee4f 100644 --- a/include/openspace/navigation/keyframenavigator.h +++ b/include/openspace/navigation/keyframenavigator.h @@ -60,13 +60,14 @@ public: }; /** - * Update camera position using the next camera pose keyframe from the timeline. - * Returns true if camera was set to a pose from the next keyframe. - * Returns false if no keyframes are available after the current time. - * \param camera A reference to the camera object to have its pose updated. - * \param ignoreFutureKeyframes true if only past keyframes are to be used. - * \returns true only if a new future keyframe is available to set camera pose. - */ + * Update camera position using the next camera pose keyframe from the timeline. + * Returns true if camera was set to a pose from the next keyframe. Returns false if + * no keyframes are available after the current time. + * + * \param camera A reference to the camera object to have its pose updated + * \param ignoreFutureKeyframes `true` if only past keyframes are to be used + * \return true only if a new future keyframe is available to set camera pose + */ bool updateCamera(Camera& camera, bool ignoreFutureKeyframes); static bool updateCamera(Camera* camera, const CameraPose prevPose, const CameraPose nextPose, double t, bool ignoreFutureKeyframes); diff --git a/include/openspace/navigation/navigationhandler.h b/include/openspace/navigation/navigationhandler.h index fa32df0e4d..ebec211fd3 100644 --- a/include/openspace/navigation/navigationhandler.h +++ b/include/openspace/navigation/navigationhandler.h @@ -151,7 +151,7 @@ public: * Set camera state from a provided navigation state next frame. The actual position * will computed from the scene in the same frame as it is set. * - * \param state the navigation state to compute a camera positon from + * \param state The navigation state to compute a camera positon from */ void setNavigationStateNextFrame(const NavigationState& state); @@ -161,14 +161,14 @@ public: * node info. The actual position will computed from the scene in the same frame as * it is set. * - * \param spec the node specification from which to compute the resulting camera pose + * \param spec The node specification from which to compute the resulting camera pose */ void setCameraFromNodeSpecNextFrame(NodeCameraStateSpec spec); /** - * \return The Lua library that contains all Lua functions available to affect the - * interaction - */ + * \return The Lua library that contains all Lua functions available to affect the + * interaction + */ static scripting::LuaLibrary luaLibrary(); private: diff --git a/include/openspace/navigation/orbitalnavigator.h b/include/openspace/navigation/orbitalnavigator.h index 0d5f440cb9..334c8cb400 100644 --- a/include/openspace/navigation/orbitalnavigator.h +++ b/include/openspace/navigation/orbitalnavigator.h @@ -43,9 +43,9 @@ #include namespace openspace { - class SceneGraphNode; class Camera; struct CameraPose; + class SceneGraphNode; struct SurfacePositionHandle; } // namespace @@ -87,10 +87,10 @@ public: void updateCameraScalingFromAnchor(double deltaTime); void resetVelocities(); - /* + /** * This function should be called on every camera interaction: for example when - * navigating using an input device, changing the focus node or starting a path or - * a session recording playback + * navigating using an input device, changing the focus node or starting a path or a + * session recording playback */ void updateOnCameraInteraction(); @@ -143,16 +143,15 @@ public: glm::quat anchorNodeToCameraRotation() const; /** - * Compute a camera position that pushed the camera position to - * a valid position over the anchor node, accounting for the - * minimal allowed distance + * Compute a camera position that pushed the camera position to a valid position over + * the anchor node, accounting for the minimal allowed distance */ glm::dvec3 pushToSurfaceOfAnchor(const glm::dvec3& cameraPosition) const; /** - * \return the Lua library that contains all Lua functions available to affect the - * OrbitalNavigator - */ + * \return The Lua library that contains all Lua functions available to affect the + * OrbitalNavigator + */ static scripting::LuaLibrary luaLibrary(); private: @@ -184,12 +183,11 @@ private: Friction _friction; - // Anchor: Node to follow and orbit + /// Anchor: Node to follow and orbit properties::StringProperty _anchor; - // Aim: Node to look at (when camera direction is reset), - // Empty string means same as anchor. - // If these are the same node we call it the `focus` node + /// Aim: Node to look at (when camera direction is reset), empty string means same as + /// anchor. If these are the same node we call it the `focus` node properties::StringProperty _aim; // Reset camera direction to the anchor node. @@ -283,6 +281,7 @@ private: * Decomposes the camera's rotation in to a global and a local rotation defined by * CameraRotationDecomposition. The global rotation defines the rotation so that the * camera points towards the reference position. + * * The local rotation defines the differential from the global to the current total * rotation so that `cameraRotation = globalRotation * localRotation`. */ @@ -290,40 +289,42 @@ private: glm::dvec3 reference); /** - * Composes a pair of global and local rotations into a quaternion that can be used - * as the world rotation for a camera. + * Composes a pair of global and local rotations into a quaternion that can be used as + * the world rotation for a camera. */ glm::dquat composeCameraRotation(const CameraRotationDecomposition& composition); - /* - * Moves and rotates the camera around the anchor node in order to maintain the - * screen space position of the aim node. Also interpolates to the aim node, when - * retargeting the aim. + /** + * Moves and rotates the camera around the anchor node in order to maintain the screen + * space position of the aim node. Also interpolates to the aim node, when retargeting + * the aim. */ CameraPose followAim(CameraPose pose, glm::dvec3 cameraToAnchor, Displacement anchorToAim); - /* - * Perform a camera roll on the local camera rotation - * \returns a local camera rotation modified with a roll. + /** + * Perform a camera roll on the local camera rotation. + * + * \return A local camera rotation modified with a roll */ glm::dquat roll(double deltaTime, const glm::dquat& localCameraRotation) const; /** * Performs rotation around the cameras x and y axes. - * \returns a local camera rotation modified with two degrees of freedom. + * + * \return A local camera rotation modified with two degrees of freedom */ glm::dquat rotateLocally(double deltaTime, const glm::dquat& localCameraRotation) const; /** * Interpolates the camera rotation based on active interpolators. - * \returns a new rotation quaternion + * + * \return A new rotation quaternion */ glm::dquat interpolateLocalRotation(double deltaTime, const glm::dquat& localCameraRotation); - Displacement interpolateRetargetAim(double deltaTime, CameraPose pose, glm::dvec3 cameraToAnchor, Displacement anchorToAim); @@ -332,7 +333,7 @@ private: /** * Modify the camera position and global rotation to rotate around the up vector - * of the current anchor based on x-wise input + * of the current anchor based on x-wise input. * * The up-vector to rotate around is determined by the "_upToUseForRotation" property */ @@ -344,18 +345,18 @@ private: * result in an orbital rotation around the object. This function does not affect the * rotation but only the position. * - * \return a position vector adjusted in the horizontal direction. + * \return A position vector adjusted in the horizontal direction. */ glm::dvec3 translateHorizontally(double deltaTime, double speedScale, const glm::dvec3& cameraPosition, const glm::dvec3& objectPosition, const glm::dquat& globalCameraRotation, const SurfacePositionHandle& positionHandle) const; - /* + /** * Adds rotation to the camera position so that it follows the rotation of the anchor - * node defined by the differential anchorNodeRotationDiff. + * node defined by the differential \p anchorNodeRotationDiff. * - * \return a position updated with the rotation defined by anchorNodeRotationDiff + * \return A position updated with the rotation defined by \p anchorNodeRotationDiff */ glm::dvec3 followAnchorNodeRotation(const glm::dvec3& cameraPosition, const glm::dvec3& objectPosition, const glm::dquat& anchorNodeRotationDiff) const; @@ -363,7 +364,7 @@ private: /** * Updates the global rotation so that it points towards the anchor node. * - * \return a global rotation quaternion defining a rotation towards the anchor node + * \return A global rotation quaternion defining a rotation towards the anchor node */ glm::dquat rotateGlobally(const glm::dquat& globalCameraRotation, const glm::dquat& aimNodeRotationDiff, @@ -371,7 +372,8 @@ private: /** * Translates the camera position towards or away from the anchor node. - * \returns a position vector adjusted in the vertical direction. + * + * \return A position vector adjusted in the vertical direction. */ glm::dvec3 translateVertically(double deltaTime, const glm::dvec3& cameraPosition, const glm::dvec3& objectPosition, @@ -380,7 +382,7 @@ private: /** * Rotates the camera around the out vector of the surface. * - * \return a quaternion adjusted to rotate around the out vector of the surface + * \return A quaternion adjusted to rotate around the out vector of the surface */ glm::dquat rotateHorizontally(double deltaTime, const glm::dquat& globalCameraRotation, @@ -389,7 +391,7 @@ private: /** * Push the camera out to the surface of the object. * - * \return a position vector adjusted to be at least _minimumAllowedDistance meters + * \return A position vector adjusted to be at least _minimumAllowedDistance meters * above the actual surface of the object */ glm::dvec3 pushToSurface(const glm::dvec3& cameraPosition, @@ -417,7 +419,7 @@ private: void resetIdleBehavior(); /** - * Apply the currently selected idle behavior to the position and rotations + * Apply the currently selected idle behavior to the position and rotations. */ void applyIdleBehavior(double deltaTime, glm::dvec3& position, glm::dquat& localRotation, glm::dquat& globalRotation); @@ -441,8 +443,8 @@ private: * vector coincides with the axis, and should be used with care. * * Used for: - * IdleBehavior::Behavior::OrbitAtConstantLat (axis = north = z-axis) and - * IdleBehavior::Behavior::OrbitAroundUp (axis = up = y-axis) + * - IdleBehavior::Behavior::OrbitAtConstantLat (axis = north = z-axis) and + * - IdleBehavior::Behavior::OrbitAroundUp (axis = up = y-axis) * * \param axis The axis to arbit around, given in model coordinates of the anchor * \param angle The rotation angle to use for the motion diff --git a/include/openspace/navigation/path.h b/include/openspace/navigation/path.h index 0d9851f6c1..5be7c88fca 100644 --- a/include/openspace/navigation/path.h +++ b/include/openspace/navigation/path.h @@ -44,12 +44,12 @@ public: AvoidCollision = 0, ZoomOutOverview, Linear, - AvoidCollisionWithLookAt // @TODO (2021-08-13, emmbr) This type right now leads - // to rapid rotations, but is useful in specific - // scenarios, e.g. close to surfaces. Later we want to - // remove it, and create a curve type that looks nicely - // at the targets when moving, avoids collisions and - // doesn't introduce sudden large changes in rotation + + // @TODO (2021-08-13, emmbr) This type right now leads to rapid rotations, but is + // useful in specific scenarios, e.g. close to surfaces. Later we want to remove + // it, and create a curve type that looks nicely at the targets when moving, + // avoids collisions and doesn't introduce sudden large changes in rotation + AvoidCollisionWithLookAt }; Path(Waypoint start, Waypoint end, Type type, @@ -59,55 +59,55 @@ public: Waypoint endPoint() const; /** - * Return the total length of the the curve for the path, in meters + * Return the total length of the the curve for the path, in meters. */ double pathLength() const; /** * Return a vector of positions corresponding to the control points of the path's - * spline curve + * spline curve. */ std::vector controlPoints() const; /** * Take a step along the current path, corresponding to the delta time step \p dt, and * return the resulting camera pose. The \p speedScale is a factor that will be - * multiplied with the traversal speed + * multiplied with the traversal speed. */ CameraPose traversePath(double dt, float speedScale = 1.f); /** * Function that can be used to permaturely quit a path, for example when skipping - * to the end + * to the end. */ void quitPath(); /** * Return the identifer of the node that is the current appropriate anchor node, of * the start and end waypoint's reference node. Dtermined based on how far along the - * path we have traveled + * path we have traveled. */ std::string currentAnchor() const; /** - * Return wether the path has reached its end point or not + * Return wether the path has reached its end point or not. */ bool hasReachedEnd() const; /** * Compute the interpolated camera pose at a certain distance along a *linear* * path. Note that the linear path is a special case, to avoid risks of precision - * problems for long paths + * problems for long paths. */ CameraPose linearInterpolatedPose(double distance, double displacement); /** - * Compute the interpolated camera pose at a certain distance along the path + * Compute the interpolated camera pose at a certain distance along the path. */ CameraPose interpolatedPose(double distance) const; /** - * Reset variables used to play back path + * Reset variables used to play back path. */ void resetPlaybackVariables(); @@ -116,49 +116,49 @@ public: private: /** * Interpolate between the paths start and end rotation using the approach that - * corresponds to the path's curve type. The interpolation parameter \p t is the - * same as for the position interpolation, i.e. the relative traveled distance - * along the path, in [0, 1] + * corresponds to the path's curve type. The interpolation parameter \p t is the same + * as for the position interpolation, i.e. the relative traveled distance along the + * path, in [0, 1]. * - * \param t The interpolation parameter, given as the relative traveled distance - along the path, in [0, 1] + * \param t The interpolation parameter, given as the relative traveled distance along + * the path, in [0, 1] */ glm::dquat interpolateRotation(double t) const; /** - * Compute the interpolated rotation quaternion using an eased SLERP approach + * Compute the interpolated rotation quaternion using an eased SLERP approach. * - * \param t The interpolation variable for the rotatation interpolation. - * Should be the relative traveled distance, in [0, 1] + * \param t The interpolation variable for the rotatation interpolation. Should be the + * relative traveled distance, in [0, 1] */ glm::dquat easedSlerpRotation(double t) const; /** - * Compute the interpolated rotation quaternion using a method that is customized - * for linear paths. The camera will first interpoalte to look at the targetted - * node, and keep doing so for most of the path. At the end, when within a certain - * distance from the target, the rotation is interpolated so that the camera ends up - * in the target pose at the end of the path. + * Compute the interpolated rotation quaternion using a method that is customized for + * linear paths. The camera will first interpoalte to look at the targetted node, and + * keep doing so for most of the path. At the end, when within a certain distance from + * the target, the rotation is interpolated so that the camera ends up in the target + * pose at the end of the path. * - * \param t The interpolation variable for the rotatation interpolation. - * Should be the relative traveled distance, in [0, 1] + * \param t The interpolation variable for the rotatation interpolation. Should be the + * relative traveled distance, in [0, 1] */ glm::dquat linearPathRotation(double t) const; /** * Compute the interpolated rotation quaternion using an approach that first - * interpolates to look at the start node, and then the end node, before - * interpolating to the end rotation + * interpolates to look at the start node, and then the end node, before interpolating + * to the end rotation. * - * \param t The interpolation variable for the rotatation interpolation. - * Should be the relative traveled distance, in [0, 1] + * \param t The interpolation variable for the rotatation interpolation. Should be the + * relative traveled distance, in [0, 1] */ glm::dquat lookAtTargetsRotation(double t) const; /** * Evaluate the current traversal speed along the path, based on the currently - * traveled distance. The final speed will be scaled to match the desired duration - * for the path (which might have been specified by the user) + * traveled distance. The final speed will be scaled to match the desired duration for + * the path (which might have been specified by the user). * * \param traveledDistance The current distance traveled along the path, in meters */ @@ -180,13 +180,13 @@ private: }; /** - * Create a path based on an instruction given as a dictionary. (See top of cpp file - * for documentation on keys and values for the dictionary.) - * If /p forceType is specified, that type will primarily be used as the type for the - * created path. Secondly, the type will be read from the dictionary, and lastly it will - * use the default from PathNavigator. + * Create a path based on an instruction given as a dictionary (see top of cpp file + * for documentation on keys and values for the dictionary). If \p forceType is specified, + * that type will primarily be used as the type for the created path. Secondly, the type + * will be read from the dictionary, and lastly it will use the default from + * PathNavigator. * - * \return the created path + * \return The created path */ Path createPathFromDictionary(const ghoul::Dictionary& dictionary, std::optional forceType = std::nullopt); diff --git a/include/openspace/navigation/pathcurve.h b/include/openspace/navigation/pathcurve.h index 7e8e549e71..5aa8deed13 100644 --- a/include/openspace/navigation/pathcurve.h +++ b/include/openspace/navigation/pathcurve.h @@ -46,7 +46,7 @@ public: virtual ~PathCurve() = 0; /** - * Return the length of the curve, in meters + * Return the length of the curve, in meters. */ double length() const; @@ -56,7 +56,7 @@ public: * the full length of the path. * * Can be overridden by subclasses that want more control over the position - * interpolation + * interpolation. */ virtual glm::dvec3 positionAt(double relativeDistance) const; @@ -66,27 +66,26 @@ public: * position. Note that u does not correspond to the relatively traveled distance. * * Can be overridden by subclasses that want more control over the position - * interpolation + * interpolation. */ virtual glm::dvec3 interpolate(double u) const; /** - * Return the positions defining the control points for the spline interpolation + * Return the positions defining the control points for the spline interpolation. */ std::vector points() const; protected: /** - * Precompute information related to the spline parameters that are - * needed for arc length reparameterization. Must be called after - * control point creation. + * Precompute information related to the spline parameters that are needed for arc + * length reparameterization. Must be called after control point creation. */ void initializeParameterData(); /** - * Compute curve parameter u that matches the input arc length s. - * Input s is a length value in meters, in the range [0, _totalLength]. - * The returned curve parameter u is in range [0, 1]. + * Compute curve parameter u that matches the input arc length s. Input s is a length + * value in meters, in the range [0, _totalLength]. The returned curve parameter u is + * in range [0, 1]. */ double curveParameter(double s) const; diff --git a/include/openspace/navigation/pathnavigator.h b/include/openspace/navigation/pathnavigator.h index 97a19ba703..1cd6082035 100644 --- a/include/openspace/navigation/pathnavigator.h +++ b/include/openspace/navigation/pathnavigator.h @@ -81,24 +81,25 @@ public: const std::vector& relevantNodes(); /** - * Find a node close to the given node. Closeness is determined by a factor times - * the bounding sphere of the object - * \return pointer to the SGN if one was found, nullptr otherwise - */ + * Find a node close to the given node. Closeness is determined by a factor times + * the bounding sphere of the object. + * + * \return Pointer to the SGN if one was found, nullptr otherwise + */ static SceneGraphNode* findNodeNearTarget(const SceneGraphNode* node); /** - * \return The Lua library that contains all Lua functions available to affect the - * path navigation - */ + * \return The Lua library that contains all Lua functions available to affect the + * path navigation + */ static scripting::LuaLibrary luaLibrary(); private: void handlePathEnd(); /** - * Populate list of nodes that are relevant for collision checks, etc - */ + * Populate list of nodes that are relevant for collision checks, etc. + */ void findRelevantNodes(); void removeRollRotation(CameraPose& pose, double deltaTime); diff --git a/include/openspace/navigation/waypoint.h b/include/openspace/navigation/waypoint.h index c884adad20..57dca42b10 100644 --- a/include/openspace/navigation/waypoint.h +++ b/include/openspace/navigation/waypoint.h @@ -59,7 +59,7 @@ private: /** * Compute a waypoint from the current camera position. * - * \return the computed WayPoint + * \return The computed WayPoint */ Waypoint waypointFromCamera(); @@ -76,14 +76,14 @@ struct NodeCameraStateSpec { * where the camera will be facing the given node. If there is a 'Sun' node in the scene, * it will possibly be used to compute a position on the lit side of the object. * - * \param spec details about the node and state to create the waypoint from. Minimal - * information is the identifier of the node, but a position or height - * above the bounding sphere may also be given. - * \param startPoint an optional previous waypoint. If not specified, the current camera + * \param spec Details about the node and state to create the waypoint from. Minimal + * information is the identifier of the node, but a position or height above + * the bounding sphere may also be given. + * \param startPoint An optional previous waypoint. If not specified, the current camera * position will be used. - * \param useLinear if true, the new waypoint will be computed along a straight line + * \param useLinear If `true`, the new waypoint will be computed along a straight line * from the start waypoint to the scene graph node or position. - * \return the computed WayPoint + * \return The computed WayPoint */ Waypoint computeWaypointFromNodeInfo(const NodeCameraStateSpec& spec, std::optional startPoint = std::nullopt, bool useLinear = false); diff --git a/include/openspace/network/messagestructures.h b/include/openspace/network/messagestructures.h index 909e7284bd..2e6999523e 100644 --- a/include/openspace/network/messagestructures.h +++ b/include/openspace/network/messagestructures.h @@ -66,7 +66,7 @@ struct CameraKeyframe { double _timestamp = 0.0; - void serialize(std::vector &buffer) const { + void serialize(std::vector& buffer) const { // Add position buffer.insert( buffer.end(), diff --git a/include/openspace/network/messagestructureshelper.h b/include/openspace/network/messagestructureshelper.h index 3c0c2678d2..3133c87923 100644 --- a/include/openspace/network/messagestructureshelper.h +++ b/include/openspace/network/messagestructureshelper.h @@ -30,25 +30,27 @@ namespace openspace::datamessagestructures { /** - * Method that creates a CameraKeyframe object and populates - * it with the current properties of the camera from the navigation handler. - * \returns CameraKeyframe with current state from NavigationHandler + * Method that creates a CameraKeyframe object and populates it with the current + * properties of the camera from the navigation handler. + * + * \return CameraKeyframe with current state from NavigationHandler */ CameraKeyframe generateCameraKeyframe(); /** - * Method that creates a TimeKeyframe object and populates - * it with the current time values from the application time manager. - * \returns TimeKeyframe The time keyframe + * Method that creates a TimeKeyframe object and populates it with the current time values + * from the application time manager. + * + * \return TimeKeyframe The time keyframe */ TimeKeyframe generateTimeKeyframe(); /** - * Method that creates a ScriptMessage object from a given script - * string, and populates the ScriptMessage with the script and timestamp - * of the current application time. + * Method that creates a ScriptMessage object from a given script string, and populates + * the ScriptMessage with the script and timestamp of the current application time. + * * \param script The script to execute in std::string form - * \returns ScriptMessage The ScriptMessage data structure with script + * \return ScriptMessage The ScriptMessage data structure with script */ ScriptMessage generateScriptMessage(std::string script); diff --git a/include/openspace/network/parallelpeer.h b/include/openspace/network/parallelpeer.h index 9a0d3ab599..2e852d2808 100644 --- a/include/openspace/network/parallelpeer.h +++ b/include/openspace/network/parallelpeer.h @@ -66,9 +66,9 @@ public: double latencyStandardDeviation() const; /** - * Returns the Lua library that contains all Lua functions available to affect the - * remote OS parallel connection. - */ + * Returns the Lua library that contains all Lua functions available to affect the + * remote OS parallel connection. + */ static scripting::LuaLibrary luaLibrary(); ParallelConnection::Status status(); int nConnections(); diff --git a/include/openspace/properties/numericalproperty.h b/include/openspace/properties/numericalproperty.h index 2ae25ae160..dc7cc814c1 100644 --- a/include/openspace/properties/numericalproperty.h +++ b/include/openspace/properties/numericalproperty.h @@ -73,9 +73,10 @@ protected: std::string generateAdditionalJsonDescription() const override; /** - * convert a lua formatted value to a JSON formatted value - * @param luaValue - * @return a json formatted string representation of the given lua value + * convert a lua formatted value to a JSON formatted value. + * + * \param luaValue + * \return A JSON formatted string representation of the given Lua value */ std::string luaToJson(std::string luaValue) const; diff --git a/include/openspace/properties/optionproperty.h b/include/openspace/properties/optionproperty.h index 2bb2366324..f115c05608 100644 --- a/include/openspace/properties/optionproperty.h +++ b/include/openspace/properties/optionproperty.h @@ -33,15 +33,15 @@ namespace openspace::properties { /** * The OptionProperty is a property that provides a number of predefined (using the - * addOption method) options consisting of a `description` and a `value`. The available + * #addOption method) options consisting of a `description` and a `value`. The available * options can be queried using the options method. Only values representing valid options - * can be used to set this property, or an error will be logged + * can be used to set this property, or an error will be logged. */ class OptionProperty : public IntProperty { public: /** - * The struct storing a single option consisting of an integer `value` and a - * `string` description. + * The struct storing a single option consisting of an integer `value` and a `string` + * description. */ struct Option { int value; @@ -57,7 +57,8 @@ public: * The constructor delegating the `identifier` and the `guiName` to its super class. * * \param info The PropertyInfo structure that contains all the required static - * information for initializing this Property. + * information for initializing this Property + * * \pre \p info.identifier must not be empty * \pre \p info.guiName must not be empty */ @@ -67,7 +68,7 @@ public: * The constructor delegating the `identifier` and the `guiName` to its super class. * * \param info The PropertyInfo structure that contains all the required static - * information for initializing this Property. + * information for initializing this Property * \param displayType Optional DisplayType for GUI (default RADIO) * * \pre \p info.identifier must not be empty @@ -123,7 +124,7 @@ public: const std::vector