Make DocumentationEngine into a singleton object

Add documentation to DocumentationEngine
Add unique identifier to Documentation class (and enforce in DocumentationEngine)
This commit is contained in:
Alexander Bock
2016-09-19 09:31:34 +02:00
parent 29c989ab82
commit 0a13d5430f
7 changed files with 93 additions and 88 deletions

View File

@@ -206,16 +206,25 @@ struct Documentation {
/**
* Creates a Documentation with a human-readable \p name and a list of \p entries.
* \param name The human-readable name of this Documentation
* \param id A unique identifier which can be used by applications (or other
* Documentation%s to reference this entry
* \param entries A list of DocumentationEntry%s that describe the individual keys for
* this entrie Documentation
* \param exhaustive Determines whether the \p entries are an exhaustive specification
* of the object or whether additional, potentially unused, keys are allowed
*/
Documentation(std::string name = "", DocumentationEntries entries = {},
Documentation(std::string name, std::string id, DocumentationEntries entries = {},
Exhaustive exhaustive = Exhaustive::No);
Documentation(std::string name, DocumentationEntries entries = {},
Exhaustive exhaustive = Exhaustive::No);
Documentation(DocumentationEntries entries = {}, Exhaustive exhaustive = Exhaustive::No);
/// The human-readable name of the Documentation
std::string name;
/// A unique identifier which can be used to reference this Documentation
std::string id;
/// A list of specifications that are describing this Documentation
DocumentationEntries entries;
/// A flag to say wheter the DocumentationEntries are an exhaustive description

View File

@@ -27,24 +27,55 @@
#include <openspace/documentation/documentation.h>
#include <ghoul/designpattern/singleton.h>
#include <ghoul/misc/exception.h>
namespace openspace {
namespace documentation {
class DocumentationEngine {
/**
* The DocumentationEngine has the ability to collect all Documentation%s that are
* produced in the application an write them out as a documentation file for human
* consumption.
*/
class DocumentationEngine : public ghoul::Singleton<DocumentationEngine> {
public:
struct DuplicateDocumentationException : public ghoul::RuntimeError {
DuplicateDocumentationException(Documentation documentation);
Documentation documentation;
};
/**
* Write the collected Documentation%s to disk at the \p filename in the specified
* \p type. A new file is created and silently overwritten in the location that
* \p filename is pointed to.
* \param filename The file that is to be created containing all the Documentation
* information.
* \param type The type of documentation that is written. Currently allowed values are
* \c text and \c html
*/
void writeDocumentation(const std::string& filename, const std::string& type);
void addDocumentation(Documentation doc);
/**
* Adds the \p documentation to the list of Documentation%s that are written to a
* documentation file with the writeDocumentation method.
* \param documentation The Documentation object that is to be stored for later use
* \throws DuplicateDocumentationException If the \p documentation did not have a
* unique identifier
*/
void addDocumentation(Documentation documentation);
static DocumentationEngine& ref();
private:
/// The list of all Documentation%s that are stored by the DocumentationEngine
std::vector<Documentation> _documentations;
};
} // namespace documentation
} // namespace openspace
#define DocEng (openspace::documentation::DocumentationEngine::ref())
#endif // __DOCUMENTATIONENGINE_H__

View File

@@ -55,7 +55,6 @@ class ModuleEngine;
class WindowWrapper;
class SettingsEngine;
namespace documentation { class DocumentationEngine; }
namespace interaction { class InteractionHandler; }
namespace gui { class GUI; }
//namespace scripting { class ScriptEngine; }
@@ -78,7 +77,6 @@ public:
// Guaranteed to return a valid pointer
ConfigurationManager& configurationManager();
documentation::DocumentationEngine& documentationEngine();
interaction::InteractionHandler& interactionHandler();
RenderEngine& renderEngine();
scripting::ScriptEngine& scriptEngine();
@@ -137,7 +135,6 @@ private:
// Components
std::unique_ptr<ConfigurationManager> _configurationManager;
std::unique_ptr<documentation::DocumentationEngine> _documentationEngine;
std::unique_ptr<interaction::InteractionHandler> _interactionHandler;
std::unique_ptr<RenderEngine> _renderEngine;
std::unique_ptr<scripting::ScriptEngine> _scriptEngine;

View File

@@ -82,12 +82,22 @@ DocumentationEntry::DocumentationEntry(std::string key, Verifier* v, std::string
optional)
{}
Documentation::Documentation(std::string n, DocumentationEntries entries, Exhaustive exh)
Documentation::Documentation(std::string n, std::string id, DocumentationEntries entries,
Exhaustive exh)
: name(std::move(n))
, id(std::move(id))
, entries(std::move(entries))
, exhaustive(std::move(exh))
{}
Documentation::Documentation(std::string n, DocumentationEntries entries, Exhaustive exh)
: Documentation(n, "", entries, exh)
{}
Documentation::Documentation(DocumentationEntries entries, Exhaustive exh)
: Documentation("", "", entries, exh)
{}
TestResult testSpecification(const Documentation& d, const ghoul::Dictionary& dict) {
TestResult result;
result.success = true;

View File

@@ -30,9 +30,25 @@
#include <fstream>
#include <fmt/format.h>
namespace openspace {
namespace documentation {
DocumentationEngine::DuplicateDocumentationException::DuplicateDocumentationException(
Documentation documentation)
: ghoul::RuntimeError(fmt::format(
"Duplicate Documentation with name '{}' and id '{}'",
documentation.name,
documentation.id
))
, documentation(std::move(documentation))
{}
DocumentationEngine& DocumentationEngine::ref() {
static DocumentationEngine engine;
return engine;
}
std::string generateTextDocumentation(const Documentation& d, int& indentLevel) {
using namespace std::string_literals;
@@ -59,7 +75,7 @@ std::string generateTextDocumentation(const Documentation& d, int& indentLevel)
if (tv) {
// We have a TableVerifier, so we need to recurse
++indentLevel;
result += generateTextDocumentation({ "", tv->documentations }, indentLevel);
result += generateTextDocumentation({ "", "", tv->documentations }, indentLevel);
result = result.substr(0, result.size() - 2);
--indentLevel;
}
@@ -89,7 +105,7 @@ std::string generateJsonDocumentation(const Documentation& d) {
result << "\"type\": \"" << p.verifier->type() << "\",";
TableVerifier* tv = dynamic_cast<TableVerifier*>(p.verifier.get());
if (tv) {
std::string json = generateJsonDocumentation({ "", tv->documentations });
std::string json = generateJsonDocumentation({ "", "", tv->documentations });
// We have a TableVerifier, so we need to recurse
result << "\"restrictions\": " << json << ",";
}
@@ -132,7 +148,7 @@ std::string generateHtmlDocumentation(const Documentation& d) {
<< "\t\t</tr>\n"
<< "\t</thead>\n"
<< "\t<tbody>\n"
<< generateHtmlDocumentation({ "", tv->documentations })
<< generateHtmlDocumentation({ "", "", tv->documentations })
<< "\t</tbody>\n"
<< "</table>\n"
<< "</td>\n";
@@ -220,7 +236,18 @@ void DocumentationEngine::writeDocumentation(const std::string& f, const std::st
}
void DocumentationEngine::addDocumentation(Documentation doc) {
_documentations.push_back(std::move(doc));
auto it = std::find_if(
_documentations.begin(),
_documentations.end(),
[doc](const Documentation& d) { return doc.id == d.id; }
);
if (it != _documentations.end()) {
throw DuplicateDocumentationException(std::move(doc));
}
else {
_documentations.push_back(std::move(doc));
}
}
} // namespace documentation

View File

@@ -121,7 +121,6 @@ OpenSpaceEngine* OpenSpaceEngine::_engine = nullptr;
OpenSpaceEngine::OpenSpaceEngine(std::string programName,
std::unique_ptr<WindowWrapper> windowWrapper)
: _configurationManager(new ConfigurationManager)
, _documentationEngine(new documentation::DocumentationEngine)
, _interactionHandler(new interaction::InteractionHandler)
, _renderEngine(new RenderEngine)
, _scriptEngine(new scripting::ScriptEngine)
@@ -164,8 +163,8 @@ OpenSpaceEngine::OpenSpaceEngine(std::string programName,
ghoul::systemcapabilities::SystemCapabilities::initialize();
TransformationManager::initialize();
_documentationEngine->addDocumentation(ConfigurationManager::Documentation());
_documentationEngine->addDocumentation(Scene::Documentation());
DocEng.addDocumentation(ConfigurationManager::Documentation());
DocEng.addDocumentation(Scene::Documentation());
}
OpenSpaceEngine::~OpenSpaceEngine() {
@@ -304,7 +303,7 @@ bool OpenSpaceEngine::create(int argc, char** argv,
// can be added as well
for (OpenSpaceModule* m : _engine->_moduleEngine->modules()) {
for (auto&& doc : m->documentations()) {
_engine->_documentationEngine->addDocumentation(doc);
DocEng.addDocumentation(doc);
}
}
@@ -444,7 +443,7 @@ bool OpenSpaceEngine::initialize() {
std::string documentationFile;
configurationManager().getValue(DocumentationFile, documentationFile);
documentationFile = absPath(documentationFile);
_documentationEngine->writeDocumentation(documentationFile, documentationType);
DocEng.writeDocumentation(documentationFile, documentationType);
}
const std::string FactoryDocumentationType =
@@ -1052,11 +1051,6 @@ void OpenSpaceEngine::disableBarrier() {
_windowWrapper->setBarrier(false);
}
documentation::DocumentationEngine& OpenSpaceEngine::documentationEngine() {
ghoul_assert(_documentationEngine, "DocumentationEngine must not be nullptr");
return *_documentationEngine;
}
NetworkEngine& OpenSpaceEngine::networkEngine() {
ghoul_assert(_networkEngine, "NetworkEngine must not be nullptr");
return *_networkEngine;

View File

@@ -98,7 +98,6 @@ TEST_F(DocumentationTest, InitializerConstructor) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{
// Basic Verifiers
{"BoolVerifier", new BoolVerifier },
@@ -162,7 +161,6 @@ TEST_F(DocumentationTest, BoolVerifier) {
using namespace openspace::documentation;
Documentation doc {
"",
{{ "Bool", new BoolVerifier }}
};
@@ -198,7 +196,6 @@ TEST_F(DocumentationTest, DoubleVerifier) {
using namespace openspace::documentation;
Documentation doc {
"",
{{ "Double", new DoubleVerifier }}
};
@@ -234,7 +231,6 @@ TEST_F(DocumentationTest, IntVerifier) {
using namespace openspace::documentation;
Documentation doc {
"",
{{ "Int", new IntVerifier }}
};
@@ -277,7 +273,6 @@ TEST_F(DocumentationTest, StringVerifier) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "String", new StringVerifier }}
};
@@ -311,7 +306,6 @@ TEST_F(DocumentationTest, TableVerifierType) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Table", new TableVerifier }}
};
@@ -346,7 +340,6 @@ TEST_F(DocumentationTest, MixedVerifiers) {
using namespace std::string_literals;
Documentation doc {
"Test",
{
{ "Bool", new BoolVerifier },
{ "Double", new DoubleVerifier },
@@ -401,7 +394,6 @@ TEST_F(DocumentationTest, NestedTables) {
using namespace std::string_literals;
Documentation doc {
"Test",
{
{ "Outer_Int", new IntVerifier },
{ "Outer_Table", new TableVerifier({
@@ -553,7 +545,6 @@ TEST_F(DocumentationTest, Optional) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{
{ "Bool_Force", new BoolVerifier, "", Optional::No },
{ "Bool_Optional", new BoolVerifier, "", Optional::Yes }
@@ -607,7 +598,6 @@ TEST_F(DocumentationTest, RequiredInOptional) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{
"a",
new TableVerifier({
@@ -669,7 +659,6 @@ TEST_F(DocumentationTest, Exhaustive) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntVerifier }},
Exhaustive::Yes
};
@@ -708,7 +697,6 @@ TEST_F(DocumentationTest, NestedExhaustive) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Table", new TableVerifier(
{ { "a", new IntVerifier } },
Exhaustive::Yes
@@ -738,10 +726,7 @@ TEST_F(DocumentationTest, NestedExhaustive) {
TEST_F(DocumentationTest, EmptyEntriesNonExhaustive) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{}
};
Documentation doc;
ghoul::Dictionary positive {};
TestResult positiveRes = testSpecification(doc, positive);
@@ -760,7 +745,6 @@ TEST_F(DocumentationTest, EmptyEntriesExhaustive) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{},
Exhaustive::Yes
};
@@ -784,7 +768,6 @@ TEST_F(DocumentationTest, EmptyNestedExhaustive) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{
"Table",
new TableVerifier(
@@ -818,7 +801,6 @@ TEST_F(DocumentationTest, LessInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntLessVerifier(5) }}
};
@@ -843,7 +825,6 @@ TEST_F(DocumentationTest, LessDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleLessVerifier(5.0) }}
};
@@ -868,7 +849,6 @@ TEST_F(DocumentationTest, LessEqualInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntLessEqualVerifier(5) }}
};
@@ -900,7 +880,6 @@ TEST_F(DocumentationTest, LessEqualDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleLessEqualVerifier(5.0) }}
};
@@ -932,7 +911,6 @@ TEST_F(DocumentationTest, GreaterInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntGreaterVerifier(5) }}
};
@@ -957,7 +935,6 @@ TEST_F(DocumentationTest, GreaterDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleGreaterVerifier(5.0) }}
};
@@ -982,7 +959,6 @@ TEST_F(DocumentationTest, GreaterEqualInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntGreaterEqualVerifier(5) }}
};
@@ -1014,7 +990,6 @@ TEST_F(DocumentationTest, GreaterEqualDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleGreaterEqualVerifier(5.0) }}
};
@@ -1046,7 +1021,6 @@ TEST_F(DocumentationTest, EqualBool) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Bool", new BoolEqualVerifier(true) }}
};
@@ -1071,7 +1045,6 @@ TEST_F(DocumentationTest, EqualInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntEqualVerifier(1) }}
};
@@ -1096,7 +1069,6 @@ TEST_F(DocumentationTest, EqualDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleEqualVerifier(1.0) }}
};
@@ -1122,7 +1094,6 @@ TEST_F(DocumentationTest, EqualString) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "String", new StringEqualVerifier("string"s) }}
};
@@ -1147,7 +1118,6 @@ TEST_F(DocumentationTest, UnequalBool) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Bool", new BoolUnequalVerifier(true) }}
};
@@ -1172,7 +1142,6 @@ TEST_F(DocumentationTest, UnequalInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntUnequalVerifier(1) }}
};
@@ -1197,7 +1166,6 @@ TEST_F(DocumentationTest, UnequalDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleUnequalVerifier(1.0) }}
};
@@ -1223,7 +1191,6 @@ TEST_F(DocumentationTest, UnequalString) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "String", new StringUnequalVerifier("string"s) }}
};
@@ -1248,7 +1215,6 @@ TEST_F(DocumentationTest, ListBool) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Bool" , new BoolInListVerifier({ true }) }}
};
@@ -1273,7 +1239,6 @@ TEST_F(DocumentationTest, ListInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int" , new IntInListVerifier({ 0, 1, 2 }) }}
};
@@ -1305,7 +1270,6 @@ TEST_F(DocumentationTest, ListDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double" , new DoubleInListVerifier({ 0.0, 1.0, 2.0 }) }}
};
@@ -1338,7 +1302,6 @@ TEST_F(DocumentationTest, ListString) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "String" , new StringInListVerifier({ "0"s, "1"s, "2"s }) }}
};
@@ -1370,7 +1333,6 @@ TEST_F(DocumentationTest, NotListBool) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Bool" , new BoolNotInListVerifier({ true }) }}
};
@@ -1395,7 +1357,6 @@ TEST_F(DocumentationTest, NotListInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int" , new IntNotInListVerifier({ 0, 1, 2 }) }}
};
@@ -1427,7 +1388,6 @@ TEST_F(DocumentationTest, NotListDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double" , new DoubleNotInListVerifier({ 0.0, 1.0, 2.0 }) }}
};
@@ -1460,7 +1420,6 @@ TEST_F(DocumentationTest, NotListString) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "String" , new StringNotInListVerifier({ "0"s, "1"s, "2"s }) }}
};
@@ -1492,7 +1451,6 @@ TEST_F(DocumentationTest, AnnotationBool) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Bool", new BoolAnnotationVerifier("Bool") }}
};
@@ -1517,7 +1475,6 @@ TEST_F(DocumentationTest, AnnotationInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new IntAnnotationVerifier("Int") }}
};
@@ -1542,7 +1499,6 @@ TEST_F(DocumentationTest, AnnotationDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new DoubleAnnotationVerifier("Double") }}
};
@@ -1568,7 +1524,6 @@ TEST_F(DocumentationTest, AnnotationString) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "String", new StringAnnotationVerifier("String") }}
};
@@ -1593,7 +1548,6 @@ TEST_F(DocumentationTest, AnnotationTable) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Table", new TableAnnotationVerifier("Table") }}
};
@@ -1618,7 +1572,6 @@ TEST_F(DocumentationTest, InRangeInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new InRangeVerifier<IntVerifier>(0, 5) }}
};
@@ -1657,7 +1610,6 @@ TEST_F(DocumentationTest, InRangeDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new InRangeVerifier<DoubleVerifier>(0.0, 5.0) }}
};
@@ -1703,7 +1655,6 @@ TEST_F(DocumentationTest, NotInRangeInt) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Int", new NotInRangeVerifier<IntVerifier>(0, 5) }}
};
@@ -1753,7 +1704,6 @@ TEST_F(DocumentationTest, NotInRangeDouble) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "Double", new NotInRangeVerifier<DoubleVerifier>(0.0, 5.0) }}
};
@@ -1803,7 +1753,6 @@ TEST_F(DocumentationTest, Wildcard) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ DocumentationEntry::Wildcard, new IntVerifier }}
};
@@ -1860,7 +1809,6 @@ TEST_F(DocumentationTest, WildcardMixed) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{
{ DocumentationEntry::Wildcard, new IntVerifier },
{ "b", new IntGreaterVerifier(5) }
@@ -1935,7 +1883,6 @@ TEST_F(DocumentationTest, AndOperator) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{
{ "a", new AndVerifier(
new IntGreaterEqualVerifier(2), new IntLessEqualVerifier(5)
@@ -1975,7 +1922,6 @@ TEST_F(DocumentationTest, OrOperator) {
using namespace std::string_literals;
Documentation doc {
"Test",
{{ "a", new OrVerifier(new StringVerifier, new IntVerifier)}}
};
@@ -2007,7 +1953,6 @@ TEST_F(DocumentationTest, BoolVector2Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{{ "a", new BoolVector2Verifier }}
};
@@ -2041,7 +1986,6 @@ TEST_F(DocumentationTest, IntVector2Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new IntVector2Verifier } }
};
@@ -2074,8 +2018,7 @@ TEST_F(DocumentationTest, IntVector2Verifier) {
TEST_F(DocumentationTest, DoubleVector2Verifier) {
using namespace openspace::documentation;
Documentation doc{
"Test",
Documentation doc {
{ { "a", new DoubleVector2Verifier } }
};
@@ -2109,7 +2052,6 @@ TEST_F(DocumentationTest, BoolVector3Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new BoolVector3Verifier } }
};
@@ -2143,7 +2085,6 @@ TEST_F(DocumentationTest, IntVector3Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new IntVector3Verifier } }
};
@@ -2177,7 +2118,6 @@ TEST_F(DocumentationTest, DoubleVector3Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new DoubleVector3Verifier } }
};
@@ -2211,7 +2151,6 @@ TEST_F(DocumentationTest, BoolVector4Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new BoolVector4Verifier } }
};
@@ -2245,7 +2184,6 @@ TEST_F(DocumentationTest, IntVector4Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new IntVector4Verifier } }
};
@@ -2279,7 +2217,6 @@ TEST_F(DocumentationTest, DoubleVector4Verifier) {
using namespace openspace::documentation;
Documentation doc {
"Test",
{ { "a", new DoubleVector4Verifier } }
};