Merge branch 'develop' of https://github.com/OpenSpace/OpenSpace into develop

include/openspace/documentation/documentation.h

@@ -69,11 +69,36 @@ struct TestResult {
         /// The Reason that caused this offense
         Reason reason;
     };
+    
+    /**
+     * A warning is some value that that does not exactly adhere to the specification, but
+     * that also does not violate so badly to warrant an Offense. This, for example, could
+     * be that a value is marked deprecated and should not be used anymore as the value
+     * might be removed in a latter version.
+     */
+    struct Warning {
+        /**
+         * The reason for the warning
+         */
+        enum class Reason {
+            Deprecated          ///< The value is marked as deprecated and should not used
+        };
+
+        /// The offending key that caused the Warning. In the case of a nested table,
+        /// this value will be the fully qualified name of the key
+        std::string offender;
+        /// The Reason that caused this Warning
+        Reason reason;
+    };
+
+
     /// Is \c true if the TestResult is positive, \c false otherwise
     bool success;
     /// Contains a list of offenses that were found in the test. Is empty if
     /// TestResult::Success is \c true
     std::vector<Offense> offenses;
+    /// Contains a list of warnings that were found in the test
+    std::vector<Warning> warnings;
 };
 
 /**

include/openspace/documentation/verifier.h

@@ -665,6 +665,33 @@ struct AnnotationVerifier : public T {
     std::string annotation;
 };
 
+/**
+ * This Verifier is a marker that performs the same testing as the \c T parameter, but
+ * also adds a warning to the test result informing the user of the deprecation.
+ * Furthermore, the documentation will contain the word <code>(deprecated)</code> in
+ * addition to the documentation returned by \c
+ * \tparam T The Verifier that is to be marked deprecated
+ */
+template <typename T>
+struct DeprecatedVerifier : public T {
+    /**
+     * Tests the \p dictionary%s \p key using the Verifier \c T and adds a warning to the
+     * TestResult informing the caller of the deprecation.
+     * \param dictionary The ghoul::Dictionary whose \p key should be tested
+     * \param key The key inside the \p dictionary that is to be tested
+     * \return A TestResult that contains the results of the testing
+     */
+    TestResult operator()(const ghoul::Dictionary& dictionary,
+                          const std::string& key) const override;
+
+    /**
+     * Returns the documentation as reported by \c T and adds the word
+     * <code>(deprecated)</code> to it.
+     * \return The deprecated version of \c T%'s documentation
+     */
+    std::string documentation() const override;
+};
+
 /**
  * This Verifier can reference and apply other Documentation%s that have been registered
  * with a DocumentationEngine. The dependency is only resolved when the operator() is
@@ -884,6 +911,18 @@ using StringAnnotationVerifier = AnnotationVerifier<StringVerifier>;
 /// <code>ghoul::Dictionary</code>
 using TableAnnotationVerifier = AnnotationVerifier<TableVerifier>;
 
+/// A short-hand definition for a DeprecatedVerifier with a type check for \c bool
+using BoolDeprecatedVerifier = DeprecatedVerifier<BoolVerifier>;
+/// A short-hand definition for a DeprecatedVerifier with a type check for \c int
+using IntDeprecatedVerifier = DeprecatedVerifier<IntVerifier>;
+/// A short-hand definition for a DeprecatedVerifier with a type check for \c double
+using DoubleDeprecatedVerifier = DeprecatedVerifier<DoubleVerifier>;
+/// A short-hand definition for a DeprecatedVerifier with a type check for \c string
+using StringDeprecatedVerifier = DeprecatedVerifier<StringVerifier>;
+/// A short-hand definition for a DeprecatedVerifier with a type check for
+/// <code>ghoul::Dictionary</code>
+using TableDeprecatedVerifier = DeprecatedVerifier<TableVerifier>;
+
 // Definitions of external templates that are instantiated in the cpp file
 // This cuts down the compilation times as almost all of the possible template types do
 // not need to be instantiated multiple times
@@ -933,7 +972,30 @@ extern template struct AnnotationVerifier<IntVerifier>;
 extern template struct AnnotationVerifier<DoubleVerifier>;
 extern template struct AnnotationVerifier<StringVerifier>;
 extern template struct AnnotationVerifier<TableVerifier>;
+extern template struct AnnotationVerifier<BoolVector2Verifier>;
+extern template struct AnnotationVerifier<IntVector2Verifier>;
+extern template struct AnnotationVerifier<DoubleVector2Verifier>;
+extern template struct AnnotationVerifier<BoolVector3Verifier>;
+extern template struct AnnotationVerifier<IntVector3Verifier>;
+extern template struct AnnotationVerifier<DoubleVector3Verifier>;
+extern template struct AnnotationVerifier<BoolVector4Verifier>;
+extern template struct AnnotationVerifier<IntVector4Verifier>;
+extern template struct AnnotationVerifier<DoubleVector4Verifier>;
 
+extern template struct DeprecatedVerifier<BoolVerifier>;
+extern template struct DeprecatedVerifier<IntVerifier>;
+extern template struct DeprecatedVerifier<DoubleVerifier>;
+extern template struct DeprecatedVerifier<StringVerifier>;
+extern template struct DeprecatedVerifier<TableVerifier>;
+extern template struct DeprecatedVerifier<BoolVector2Verifier>;
+extern template struct DeprecatedVerifier<IntVector2Verifier>;
+extern template struct DeprecatedVerifier<DoubleVector2Verifier>;
+extern template struct DeprecatedVerifier<BoolVector3Verifier>;
+extern template struct DeprecatedVerifier<IntVector3Verifier>;
+extern template struct DeprecatedVerifier<DoubleVector3Verifier>;
+extern template struct DeprecatedVerifier<BoolVector4Verifier>;
+extern template struct DeprecatedVerifier<IntVector4Verifier>;
+extern template struct DeprecatedVerifier<DoubleVector4Verifier>;
 
 } // namespace documentation
 } // namespace openspace

include/openspace/documentation/verifier.inl

@@ -263,7 +263,7 @@ NotInRangeVerifier<T>::NotInRangeVerifier(typename T::Type lower, typename T::Ty
 
 template <typename T>
 TestResult NotInRangeVerifier<T>::operator()(const ghoul::Dictionary& dict,
-                                          const std::string& key) const {
+                                             const std::string& key) const {
     TestResult res = T::operator()(dict, key);
     if (res.success) {
         typename T::Type val = dict.value<typename T::Type>(key);
@@ -299,5 +299,19 @@ std::string AnnotationVerifier<T>::documentation() const {
     return annotation;
 }
 
+template <typename T>
+TestResult DeprecatedVerifier<T>::operator()(const ghoul::Dictionary& dict,
+                                             const std::string& key) const
+{
+    TestResult res = T::operator()(dict, key);
+    res.warnings.push_back(TestResult::Warning{ key, TestResult::Warning::Reason::Deprecated });
+    return res;
+}
+
+template <typename T>
+std::string DeprecatedVerifier<T>::documentation() const {
+    return T::documentation() + " (deprecated)";
+}
+
 } // namespace documentation
 } // namespace openspace