Move documentation to their own folder

This commit is contained in:
Alexander Bock
2016-09-14 14:44:51 +02:00
parent bb52c33b04
commit dbc9b7ae4e
7 changed files with 68 additions and 5 deletions

View File

@@ -1,356 +0,0 @@
/*****************************************************************************************
* *
* OpenSpace *
* *
* Copyright (c) 2014-2016 *
* *
* Permission is hereby granted, free of charge, to any person obtaining a copy of this *
* software and associated documentation files (the "Software"), to deal in the Software *
* without restriction, including without limitation the rights to use, copy, modify, *
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to *
* permit persons to whom the Software is furnished to do so, subject to the following *
* conditions: *
* *
* The above copyright notice and this permission notice shall be included in all copies *
* or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, *
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A *
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT *
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF *
* CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE *
* OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
****************************************************************************************/
#ifndef __DOCUMENTATION_H__
#define __DOCUMENTATION_H__
#include <ghoul/misc/assert.h>
#include <ghoul/misc/boolean.h>
#include <ghoul/misc/dictionary.h>
#include <iterator>
#include <map>
#include <memory>
#include <string>
#include <type_traits>
#include <vector>
namespace openspace {
namespace documentation {
struct TestResult {
bool success;
std::vector<std::string> offenders;
};
using Optional = ghoul::Boolean;
struct Verifier {
virtual TestResult operator()(const ghoul::Dictionary& dict,
const std::string& key) const;
virtual bool test(const ghoul::Dictionary& dict, const std::string& key) const;
virtual std::string documentation() const = 0;
};
struct DocumentationEntry {
DocumentationEntry(std::string key, Verifier* t, Optional optional = Optional::No,
std::string doc = "");
std::string key;
std::shared_ptr<Verifier> tester;
bool optional;
std::string documentation;
};
using Documentation = std::vector<DocumentationEntry>;
TestResult testSpecification(const Documentation& d, const ghoul::Dictionary& dictionary);
std::string generateDocumentation(const Documentation& d);
// General verifiers
template <typename T>
struct TemplateVerifier : public Verifier {
using Type = T;
};
struct BoolVerifier : public TemplateVerifier<bool> {
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
};
struct DoubleVerifier : public TemplateVerifier<double> {
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
};
struct IntVerifier : public TemplateVerifier<int> {
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
};
struct StringVerifier : public TemplateVerifier<std::string> {
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
};
struct TableVerifier : public TemplateVerifier<ghoul::Dictionary> {
TableVerifier(Documentation d = {});
TestResult operator()(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
Documentation doc;
};
// Operator Verifiers
template <typename T>
struct LessVerifier : public T {
static_assert(!std::is_base_of_v<BoolVerifier, T>, "T cannot be BoolVerifier");
static_assert(!std::is_base_of_v<StringVerifier, T>, "T cannot be StringVerifier");
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
LessVerifier(typename T::Type value);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const;
typename T::Type value;
};
template <typename T>
struct LessEqualVerifier : public T {
static_assert(!std::is_base_of_v<BoolVerifier, T>, "T cannot be BoolVerifier");
static_assert(!std::is_base_of_v<StringVerifier, T>, "T cannot be StringVerifier");
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
LessEqualVerifier(typename T::Type value);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type value;
};
template <typename T>
struct GreaterVerifier : public T {
static_assert(!std::is_base_of_v<BoolVerifier, T>, "T cannot be BoolVerifier");
static_assert(!std::is_base_of_v<StringVerifier, T>, "T cannot be StringVerifier");
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
GreaterVerifier(typename T::Type value);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type value;
};
template <typename T>
struct GreaterEqualVerifier : public T {
static_assert(!std::is_base_of_v<BoolVerifier, T>, "T cannot be BoolVerifier");
static_assert(!std::is_base_of_v<StringVerifier, T>, "T cannot be StringVerifier");
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
GreaterEqualVerifier(typename T::Type value);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type value;
};
template <typename T>
struct EqualVerifier : public T {
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
EqualVerifier(typename T::Type value);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type value;
};
template <typename T>
struct UnequalVerifier : public T {
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
UnequalVerifier(typename T::Type value);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type value;
};
// List Verifiers
template <typename T>
struct InListVerifier : public T {
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
InListVerifier(std::vector<typename T::Type> values);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
std::vector<typename T::Type> values;
};
template <typename T>
struct NotInListVerifier : public T {
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
NotInListVerifier(std::vector<typename T::Type> values);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
std::vector<typename T::Type> values;
};
// Range Verifiers
template <typename T>
struct InRangeVerifier : public T {
static_assert(!std::is_base_of_v<BoolVerifier, T>, "T cannot be BoolVerifier");
static_assert(!std::is_base_of_v<StringVerifier, T>, "T cannot be StringVerifier");
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
InRangeVerifier(typename T::Type lower, typename T::Type upper);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type lower;
typename T::Type upper;
};
template <typename T>
struct NotInRangeVerifier : public T {
static_assert(!std::is_base_of_v<BoolVerifier, T>, "T cannot be BoolVerifier");
static_assert(!std::is_base_of_v<StringVerifier, T>, "T cannot be StringVerifier");
static_assert(!std::is_base_of_v<TableVerifier, T>, "T cannot be TableVerifier");
NotInRangeVerifier(typename T::Type lower, typename T::Type upper);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
typename T::Type lower;
typename T::Type upper;
};
// Misc Verifiers
template <typename T>
struct AnnotationVerifier : public T {
AnnotationVerifier(std::string annotation);
bool test(const ghoul::Dictionary& dict, const std::string& key) const override;
std::string documentation() const override;
std::string annotation;
};
using IntLessVerifier = LessVerifier<IntVerifier>;
using DoubleLessVerifier = LessVerifier<DoubleVerifier>;
using IntLessEqualVerifier = LessEqualVerifier<IntVerifier>;
using DoubleLessEqualVerifier = LessEqualVerifier<DoubleVerifier>;
using IntGreaterVerifier = GreaterVerifier<IntVerifier>;
using DoubleGreaterVerifier = GreaterVerifier<DoubleVerifier>;
using IntGreaterEqualVerifier = GreaterEqualVerifier<IntVerifier>;
using DoubleGreaterEqualVerifier = GreaterEqualVerifier<DoubleVerifier>;
using BoolEqualVerifier = EqualVerifier<BoolVerifier>;
using IntEqualVerifier = EqualVerifier<IntVerifier>;
using DoubleEqualVerifier = EqualVerifier<DoubleVerifier>;
using StringEqualVerifier = EqualVerifier<StringVerifier>;
using BoolUnequalVerifier = UnequalVerifier<BoolVerifier>;
using IntUnequalVerifier = UnequalVerifier<IntVerifier>;
using DoubleUnequalVerifier = UnequalVerifier<DoubleVerifier>;
using StringUnequalVerifier = UnequalVerifier<StringVerifier>;
using BoolInListVerifier = InListVerifier<BoolVerifier>;
using IntInListVerifier = InListVerifier<IntVerifier>;
using DoubleInListVerifier = InListVerifier<DoubleVerifier>;
using StringInListVerifier = InListVerifier<StringVerifier>;
using BoolNotInListVerifier = NotInListVerifier<BoolVerifier>;
using IntNotInListVerifier = NotInListVerifier<IntVerifier>;
using DoubleNotInListVerifier = NotInListVerifier<DoubleVerifier>;
using StringNotInListVerifier = NotInListVerifier<StringVerifier>;
using IntInRangeVerifier = InRangeVerifier<IntVerifier>;
using DoubleInRangeVerifier = InRangeVerifier<DoubleVerifier>;
using IntNotInRangeVerifier = NotInRangeVerifier<IntVerifier>;
using DoubleNotInRangeVerifier = NotInRangeVerifier<DoubleVerifier>;
using BoolAnnotationVerifier = AnnotationVerifier<BoolVerifier>;
using IntAnnotationVerifier = AnnotationVerifier<IntVerifier>;
using DoubleAnnotationVerifier = AnnotationVerifier<DoubleVerifier>;
using StringAnnotationVerifier = AnnotationVerifier<StringVerifier>;
using TableAnnotationVerifier = AnnotationVerifier<TableVerifier>;
extern template struct LessVerifier<IntVerifier>;
extern template struct LessVerifier<DoubleVerifier>;
extern template struct LessEqualVerifier<IntVerifier>;
extern template struct LessEqualVerifier<DoubleVerifier>;
extern template struct GreaterVerifier<IntVerifier>;
extern template struct GreaterVerifier<DoubleVerifier>;
extern template struct GreaterEqualVerifier<IntVerifier>;
extern template struct GreaterEqualVerifier<DoubleVerifier>;
extern template struct EqualVerifier<BoolVerifier>;
extern template struct EqualVerifier<IntVerifier>;
extern template struct EqualVerifier<DoubleVerifier>;
extern template struct EqualVerifier<StringVerifier>;
extern template struct UnequalVerifier<BoolVerifier>;
extern template struct UnequalVerifier<IntVerifier>;
extern template struct UnequalVerifier<DoubleVerifier>;
extern template struct UnequalVerifier<StringVerifier>;
extern template struct InListVerifier<BoolVerifier>;
extern template struct InListVerifier<IntVerifier>;
extern template struct InListVerifier<DoubleVerifier>;
extern template struct InListVerifier<StringVerifier>;
extern template struct NotInListVerifier<BoolVerifier>;
extern template struct NotInListVerifier<IntVerifier>;
extern template struct NotInListVerifier<DoubleVerifier>;
extern template struct NotInListVerifier<StringVerifier>;
extern template struct InRangeVerifier<IntVerifier>;
extern template struct InRangeVerifier<DoubleVerifier>;
extern template struct NotInRangeVerifier<IntVerifier>;
extern template struct NotInRangeVerifier<DoubleVerifier>;
extern template struct AnnotationVerifier<BoolVerifier>;
extern template struct AnnotationVerifier<IntVerifier>;
extern template struct AnnotationVerifier<DoubleVerifier>;
extern template struct AnnotationVerifier<StringVerifier>;
extern template struct AnnotationVerifier<TableVerifier>;
} // namespace documentation
} // namespace openspace
#include "documentation.inl"
#endif // __DOCUMENTATION_H__

View File

@@ -1,260 +0,0 @@
/*****************************************************************************************
* *
* OpenSpace *
* *
* Copyright (c) 2014-2016 *
* *
* Permission is hereby granted, free of charge, to any person obtaining a copy of this *
* software and associated documentation files (the "Software"), to deal in the Software *
* without restriction, including without limitation the rights to use, copy, modify, *
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to *
* permit persons to whom the Software is furnished to do so, subject to the following *
* conditions: *
* *
* The above copyright notice and this permission notice shall be included in all copies *
* or substantial portions of the Software. *
* *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, *
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A *
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT *
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF *
* CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE *
* OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
****************************************************************************************/
namespace std {
std::string to_string(std::string value);
}
namespace openspace {
namespace documentation {
template <typename T>
LessVerifier<T>::LessVerifier(typename T::Type value)
: value(std::move(value))
{
}
template <typename T>
bool LessVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
return T::test(dict, key) && dict.value<Type>(key) < value;
}
template <typename T>
std::string LessVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Less than: " + std::to_string(value);
}
template <typename T>
LessEqualVerifier<T>::LessEqualVerifier(typename T::Type value)
: value(std::move(value))
{}
template <typename T>
bool LessEqualVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
return T::test(dict, key) && dict.value<Type>(key) <= value;
}
template <typename T>
std::string LessEqualVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Less or equal to: " + std::to_string(value);
}
template <typename T>
GreaterVerifier<T>::GreaterVerifier(typename T::Type value)
: value(std::move(value))
{}
template <typename T>
bool GreaterVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
return T::test(dict, key) && dict.value<Type>(key) > value;
}
template <typename T>
std::string GreaterVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Greater than: " + std::to_string(value);
}
template <typename T>
GreaterEqualVerifier<T>::GreaterEqualVerifier(typename T::Type value)
: value(std::move(value))
{}
template <typename T>
bool GreaterEqualVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
return T::test(dict, key) && dict.value<Type>(key) >= value;
}
template <typename T>
std::string GreaterEqualVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Greater or equal to: " + std::to_string(value);
}
template <typename T>
EqualVerifier<T>::EqualVerifier(typename T::Type value)
: value(std::move(value))
{}
template <typename T>
bool EqualVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
return T::test(dict, key) && dict.value<Type>(key) == value;
}
template <typename T>
std::string EqualVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Equal to: " + std::to_string(value);
}
template <typename T>
UnequalVerifier<T>::UnequalVerifier(typename T::Type value)
: value(std::move(value))
{}
template <typename T>
bool UnequalVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
return T::test(dict, key) && dict.value<Type>(key) != value;
}
template <typename T>
std::string UnequalVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Unequal to: " + std::to_string(value);
}
template <typename T>
InListVerifier<T>::InListVerifier(std::vector<typename T::Type> values)
: values(std::move(values))
{}
template <typename T>
bool InListVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
if (T::test(dict, key)) {
typename T::Type value = dict.value<typename T::Type>(key);
auto it = std::find(values.begin(), values.end(), value);
return it != values.end();
}
else {
return false;
}
}
template <typename T>
std::string InListVerifier<T>::documentation() const {
std::string result = T::documentation() + '\n' + "In list {";
std::stringstream s;
std::copy(values.begin(), values.end(), std::ostream_iterator<typename T::Type>(s, ","));
std::string joined = s.str();
// We need to remove a trailing ',' at the end of the string
result += joined.substr(0, joined.size() - 1);
result += "}";
return result;
}
template <typename T>
NotInListVerifier<T>::NotInListVerifier(std::vector<typename T::Type> values)
: values(std::move(values))
{}
template <typename T>
bool NotInListVerifier<T>::test(const ghoul::Dictionary& dict, const std::string& key) const {
if (T::test(dict, key)) {
typename T::Type value = dict.value<typename T::Type>(key);
auto it = std::find(values.begin(), values.end(), value);
return it == values.end();
}
else {
return false;
}
}
template <typename T>
std::string NotInListVerifier<T>::documentation() const {
std::string result = T::documentation() + '\n' + "Not in list {";
std::stringstream s;
std::copy(values.begin(), values.end(), std::ostream_iterator<typename T::Type>(s, ","));
std::string joined = s.str();
// We need to remove a trailing ',' at the end of the string
result += joined.substr(0, joined.size() - 1);
result += "}";
return result;
}
template <typename T>
InRangeVerifier<T>::InRangeVerifier(typename T::Type lower, typename T::Type upper)
: lower(std::move(lower))
, upper(std::move(upper))
{
ghoul_assert(lower <= upper, "Lower value must be smaller or equal to upper value");
}
template <typename T>
bool InRangeVerifier<T>::test(const ghoul::Dictionary& d, const std::string& key) const {
if (T::test(d, key)) {
typename T::Type val = d.value<typename T::Type>(key);
return val >= lower && val <= upper;
}
else {
return false;
}
}
template <typename T>
std::string InRangeVerifier<T>::documentation() const {
return T::documentation() + '\n' + "In range: (" + std::to_string(lower) + "," +
std::to_string(upper) + ")";
}
template <typename T>
NotInRangeVerifier<T>::NotInRangeVerifier(typename T::Type lower, typename T::Type upper)
: lower(std::move(lower))
, upper(std::move(upper))
{
ghoul_assert(lower <= upper, "Lower value must be smaller or equal to upper value");
}
template <typename T>
bool NotInRangeVerifier<T>::test(const ghoul::Dictionary& d, const std::string& k) const {
if (T::test(d, k)) {
typename T::Type val = d.value<typename T::Type>(k);
return !(val >= lower && val <= upper);
}
else {
return false;
}
}
template <typename T>
std::string NotInRangeVerifier<T>::documentation() const {
return T::documentation() + '\n' + "Not in range: (" + std::to_string(lower) + "," +
std::to_string(upper) + ")";
}
template <typename T>
AnnotationVerifier<T>::AnnotationVerifier(std::string annotation)
: annotation(std::move(annotation))
{}
template <typename T>
bool AnnotationVerifier<T>::test(const ghoul::Dictionary& dict,
const std::string& key) const
{
return T::test(dict, key);
}
template <typename T>
std::string AnnotationVerifier<T>::documentation() const {
return T::documentation() + '\n' + annotation;
}
} // namespace documentation
} // namespace openspace