From 7ef0b0947e65546371b33420f363990537e6c2c7 Mon Sep 17 00:00:00 2001
From: tobiglaser <76131623+tobiglaser@users.noreply.github.com>
Date: Tue, 2 Aug 2022 18:11:42 +0200
Subject: [PATCH] Doxygen documentation
---
include/BackgroundControl.h | 5 ++
include/ComHandler.h | 33 +++++++++++-
include/ComState.h | 4 ++
include/RoverHandler.h | 2 +-
src/CommandListOWN.h | 16 +++---
src/CommandType.h | 16 +++++-
src/ControlModel.h | 104 ++++++++++++++++++++++++++++--------
src/ControlModelRegistry.h | 23 ++++++++
src/Element.h | 9 +++-
src/IControlModelListener.h | 4 ++
src/ObjectFileHandler.h | 22 ++++++++
11 files changed, 204 insertions(+), 34 deletions(-)
diff --git a/include/BackgroundControl.h b/include/BackgroundControl.h
index 938308d..898c9a1 100644
--- a/include/BackgroundControl.h
+++ b/include/BackgroundControl.h
@@ -1,5 +1,10 @@
#pragma once
+/**
+ * @brief What happens here is beyond my imagination.
+ * "While it is always best to believe in oneself, a little help from others can be a great blessing."
+ * - Uncle Iroh
+ */
class BackgroundControl
{
};
diff --git a/include/ComHandler.h b/include/ComHandler.h
index 2e23bb4..cc1ac23 100644
--- a/include/ComHandler.h
+++ b/include/ComHandler.h
@@ -7,7 +7,10 @@
#include <memory>
#include <vector>
-
+/**
+ * @brief Uses magic to communicate to the Rover.
+ * Implemented as Singleton using getInstance().
+ */
class ComHandler
{
private:
@@ -20,26 +23,54 @@ public:
void registerComListener(IComListener *cl);
void unregisterComListener(IComListener *cl);
bool start(std::vector<std::shared_ptr<ICommand>> commands, std::optional<Rover> rover);
+ /**
+ * @brief Will stop the execution, currently does nothing.
+ * @return always true
+ */
bool stop() { return true; }
};
+/**
+ * @brief Manages the static Singleton instance of ComHandler
+ *
+ * @return ComHandler& the Instance of ComHandler
+ */
ComHandler& ComHandler::getInstance()
{
static ComHandler instance = ComHandler();
return instance;
}
+/**
+ * @brief Registers an IComListener to ComHandler
+ * for use in an observer pattern.
+ * @param cl the raw pointer to be registered.
+ */
void ComHandler::registerComListener(IComListener *cl)
{
comListener = cl;
}
+/**
+ * @brief Unregister an IComListener from ComHandler.
+ * Unregisters the Listener only if the pointer matches
+ * the one already registered to ComHandler.
+ * @param cl the raw pointer to the Listener
+ */
void ComHandler::unregisterComListener(IComListener *cl)
{
if (comListener == cl)
comListener.reset();
}
+/**
+ * @brief Will currently always simulate the execution as the rover communitaction is not implemented.
+ *
+ * @param commands A vector of ICommands to be executed
+ * @param rover The rover to be used (currently ignored!)
+ * @return true if a Rover was given -> real execution
+ * @return false if no Rover was given -> simulation
+ */
bool ComHandler::start(std::vector<std::shared_ptr<ICommand>> commands, std::optional<Rover> rover)
{
if (rover)
diff --git a/include/ComState.h b/include/ComState.h
index 39f4493..b2f4a7f 100644
--- a/include/ComState.h
+++ b/include/ComState.h
@@ -1,5 +1,9 @@
#pragma once
+/**
+ * @brief An enumeration of the states the ComHandler can be in.
+ *
+ */
enum class ComState
{
connection_error,
diff --git a/include/RoverHandler.h b/include/RoverHandler.h
index 102121c..040dd21 100644
--- a/include/RoverHandler.h
+++ b/include/RoverHandler.h
@@ -8,7 +8,7 @@ public:
/**
* @brief Dummy/Placeholder not implemented!
* Maybe don't use References, so nobody has to guarantee any lifetimes.
- * @returns an empty Vector or - in future - a Vector of Rover references.
+ * @returns an empty Vector or - in future - a Vector of Rovers.
*/
static inline std::vector<Rover> getFreeRover()
{
diff --git a/src/CommandListOWN.h b/src/CommandListOWN.h
index ae0a897..b9e0cab 100644
--- a/src/CommandListOWN.h
+++ b/src/CommandListOWN.h
@@ -84,8 +84,8 @@ void CommandList::clear()
* @brief Adds a Command of Type to the end of the list.
* This template does not check if the given Type inherits from Command.
* @tparam Type implicit
- * @param _cmd any Command that inherits from Command
- * @return std::shared_ptr<Command> to the newly instanciated Command
+ * @param _cmd any Command that inherits from ICommand
+ * @return std::shared_ptr<ICommand> to the newly instanciated Command
*/
template <typename Type>
std::shared_ptr<ICommand> CommandList::add(const Type _cmd)
@@ -133,7 +133,7 @@ void CommandList::printCommands()
* @brief Removes the Element at _pos from the list.
*
* @param _pos of the Element to be deleted
- * @return std::shared_ptr<Command> to the Command the Element was holding
+ * @return std::shared_ptr<ICommand> to the Command the Element was holding
* or nullptr, if unsuccessful
*/
std::shared_ptr<ICommand> CommandList::remove(unsigned int _pos)
@@ -177,7 +177,7 @@ std::shared_ptr<Element> CommandList::getElement(unsigned int _pos)
* @brief Get the Command at _pos of the list utilizing CommandList::getElement.
*
* @param _pos of the wanted Command
- * @return std::shared_ptr<Command> to the wanted Command or nullptr if unsuccessful.
+ * @return std::shared_ptr<ICommand> to the wanted Command or nullptr if unsuccessful.
*/
std::shared_ptr<ICommand> CommandList::getCommand(unsigned int _pos)
{
@@ -193,10 +193,10 @@ std::shared_ptr<ICommand> CommandList::getCommand(unsigned int _pos)
}
/**
- * @brief Searches the list for a std::shared_ptr<Command>.
+ * @brief Searches the list for a std::shared_ptr<ICommand>.
*
* @param _cmd to look up.
- * @return int position of the std::shared_ptr<Command> or -1 if unsuccessful.
+ * @return int position of the std::shared_ptr<ICommand> or -1 if unsuccessful.
*/
int CommandList::getPos(std::shared_ptr<ICommand> _cmd)
{
@@ -219,7 +219,7 @@ int CommandList::getPos(std::shared_ptr<ICommand> _cmd)
* @brief Moves up an Element in the list.
* Switching the Element at _pos with the Element at _pos-1.
* @param _pos of the Element to move up
- * @return std::shared_ptr<Command> held by the moved Element or nullptr if unsuccessful.
+ * @return std::shared_ptr<ICommand> held by the moved Element or nullptr if unsuccessful.
*/
std::shared_ptr<ICommand> CommandList::moveUp(unsigned int _pos)
{
@@ -252,7 +252,7 @@ std::shared_ptr<ICommand> CommandList::moveUp(unsigned int _pos)
* Switching the Element at _pos with the Element at _pos+1.
* Probably one of these functions could use the other one with an offset, but whatever.
* @param _pos of the Element to move down
- * @return std::shared_ptr<Command> held by the moved Element or nullptr if unsuccessful.
+ * @return std::shared_ptr<ICommand> held by the moved Element or nullptr if unsuccessful.
*/
std::shared_ptr<ICommand> CommandList::moveDown(unsigned int _pos)
{
diff --git a/src/CommandType.h b/src/CommandType.h
index 2a1de73..e21e9c4 100644
--- a/src/CommandType.h
+++ b/src/CommandType.h
@@ -6,6 +6,11 @@
#include <memory>
#include <string>
+/**
+ * @brief A class used between the GUI and the ControlModel.
+ * Will display the command given during construction
+ * and instanciate new Objects of that type.
+ */
class CommandType
{
private:
@@ -19,12 +24,21 @@ public:
std::shared_ptr<ICommand> createInstance();
};
+/**
+ * @brief Construct a new CommandType:: Command Type object
+ *
+ * @param _name of the Command to be instanciated later.
+ */
CommandType::CommandType(std::string _name)
{
name = _name;
}
-
+/**
+ * @brief Creates an instance of its Command wrapped in a shared_ptr.
+ *
+ * @return std::shared_ptr<ICommand> to the new Object.
+ */
std::shared_ptr<ICommand> CommandType::createInstance()
{
if (name == IGear::gear)
diff --git a/src/ControlModel.h b/src/ControlModel.h
index f894352..0a7d498 100644
--- a/src/ControlModel.h
+++ b/src/ControlModel.h
@@ -12,6 +12,11 @@
#include "ComState.h"
#include "ObjectFileHandler.h"
+/**
+ * @brief "Central administration" of the whole ControlDeveloper.
+ * ControlModel is the mediator between the backend and the GUI.
+ * ControlModel is a Singleton.
+ */
class ControlModel : public ControlModelRegistry, IComListener
{
private:
@@ -38,46 +43,46 @@ public:
// Possible Lifetime concerns
std::array<CommandType, 3> &getCommandTypes() { return cT; }
- void setSelectedRover()
- {
- std::vector<Rover> rovers = RoverHandler::getFreeRover();
- if (!rovers.empty())
- {
- selectedRover = rovers.front();
- notifyRoverChanged();
- }
- else
- {
- selectedRover = Rover(); //some example Rover
- notifyRoverChanged();
- }
- }
+ void setSelectedRover();
- std::optional<std::string> getSelectedRoverId()
- {
- if (selectedRover)
- return selectedRover.value().getId();
- else
- return std::nullopt;
- }
+ std::optional<std::string> getSelectedRoverId();
};
+/**
+ * @brief Construct a new Control Model:: Control Model object
+ * Registers itself to ComHandler
+ */
ControlModel::ControlModel()
{
ComHandler::getInstance().registerComListener(this);
}
+/**
+ * @brief Destroy the Control Model:: Control Model object
+ * Unregisters itself from ComHandler
+ */
ControlModel::~ControlModel()
{
ComHandler::getInstance().unregisterComListener(this);
}
+/**
+ * @brief As ControlModel is Singleton, this function manages
+ * the static instance and returns a reference to it.
+ * @return ControlModel& the Instance of ControlModel
+ */
ControlModel& ControlModel::getInstance()
{
static ControlModel instance = ControlModel();
return instance;
}
+/**
+ * @brief Will notify all IControlModelListeners subscribed to ControlModel
+ * with a string corresponding to the given parameters.
+ * @param _command an optional ICommand. The Message will be getConfig() or "no Command"
+ * @param _state The ComState the ComHandler is in.
+ */
void ControlModel::commandPerformed(std::optional<std::shared_ptr<ICommand>> _command, ComState _state)
{
std::string commandPart = "";
@@ -112,6 +117,12 @@ void ControlModel::commandPerformed(std::optional<std::shared_ptr<ICommand>> _co
notifyMessageChanged("Command: " + commandPart + " - State: " + statePart);
}
+/**
+ * @brief Will gather every ICommand from the CommandList into a vector and
+ * hand it over to the ComHandler together with the selected Rover to start the
+ * execution.
+ * @return the result of ComHandler.start()
+ */
bool ControlModel::start()
{
std::vector<std::shared_ptr<ICommand>> commands;
@@ -126,11 +137,22 @@ bool ControlModel::start()
return ComHandler::getInstance().start(commands, selectedRover);
}
+/**
+ * @brief Will tell the ComHandler to stop the execution of commands
+ *
+ * @return the result of ComHandler.stop()
+ */
bool ControlModel::stop()
{
return ComHandler::getInstance().stop();
}
+/**
+ * @brief Uses ObjectFileHandler to parse a file for Commands
+ * and adds them to the CommandList
+ * @param _fileName relative Path to the file to be read.
+ * @see ObjectFileHandler
+ */
void ControlModel::readCommands(std::string _fileName)
{
ObjectFileHandler fH = ObjectFileHandler(_fileName);
@@ -142,6 +164,12 @@ void ControlModel::readCommands(std::string _fileName)
}
}
+/**
+ * @brief Gathers all Commands from the CommandList, then uses
+ * ObjectFileHandler to write them to a file
+ * @param _fileName relative Path to the file to be written to. (See ObjectFileHandler)
+ * @see ObjectFileHandler
+ */
void ControlModel::writeCommands(std::string _fileName)
{
std::vector<std::shared_ptr<ICommand>> v;
@@ -154,4 +182,38 @@ void ControlModel::writeCommands(std::string _fileName)
}
ObjectFileHandler fH = ObjectFileHandler(_fileName);
fH.write(v);
+}
+
+/**
+ * @brief Gets free Rovers from RoverHandler and sets the first
+ * one as the selectedRover.
+ * If the List is empty, e.g. during Simulation, an empty Rover is created.
+ * All subsrcribers to ControlModel are notified of the rover change.
+ */
+void ControlModel::setSelectedRover()
+{
+ std::vector<Rover> rovers = RoverHandler::getFreeRover();
+ if (!rovers.empty())
+ {
+ selectedRover = rovers.front();
+ notifyRoverChanged();
+ }
+ else
+ {
+ selectedRover = Rover(); //some example Rover
+ notifyRoverChanged();
+ }
+}
+
+/**
+ * @brief Since it is possible no rover is selected the value is optional.
+ *
+ * @return std::optional<std::string> the Id of the Rover or nullopt if no Rover was selected.
+ */
+std::optional<std::string> ControlModel::getSelectedRoverId()
+{
+if (selectedRover)
+ return selectedRover.value().getId();
+else
+ return std::nullopt;
}
\ No newline at end of file
diff --git a/src/ControlModelRegistry.h b/src/ControlModelRegistry.h
index dbfd41f..cfbbcaa 100644
--- a/src/ControlModelRegistry.h
+++ b/src/ControlModelRegistry.h
@@ -4,6 +4,10 @@
#include <memory>
#include <vector>
+/**
+ * @brief ControlModelRegistry allows another class to use the Observer pattern.
+ *
+ */
class ControlModelRegistry
{
private:
@@ -16,11 +20,21 @@ public:
void notifyRoverChanged();
};
+/**
+ * @brief Add a Listener / Subscriber / Observer to the registry.
+ *
+ * @param _listener A shared_ptr to the listener to be added.
+ */
void ControlModelRegistry::addControlModelListener(std::shared_ptr<IControlModelListener> _listener)
{
registry.push_back(_listener);
}
+/**
+ * @brief Remove a Listener / Subscriber / Observer from the registry.
+ * Removal happens if the same address is referenced.
+ * @param _listener A shared_ptr to the listener to be removed.
+ */
void ControlModelRegistry::removeControlModelListener(std::shared_ptr<IControlModelListener> _listener)
{
for (auto iter = registry.begin(); iter != registry.end(); ++iter)
@@ -33,6 +47,11 @@ void ControlModelRegistry::removeControlModelListener(std::shared_ptr<IControlMo
}
+/**
+ * @brief Calls messageUpdated() of every object in the registry.
+ *
+ * @param _message The message to be communicated to the Listeners.
+ */
void ControlModelRegistry::notifyMessageChanged(std::string _message)
{
for (auto &&i : registry)
@@ -43,6 +62,10 @@ void ControlModelRegistry::notifyMessageChanged(std::string _message)
}
}
+/**
+ * @brief Call roverUpdated() of every object in the registry,
+ * not communicating any additional data.
+ */
void ControlModelRegistry::notifyRoverChanged()
{
for (auto &&i : registry)
diff --git a/src/Element.h b/src/Element.h
index 8deeb30..d7ce090 100644
--- a/src/Element.h
+++ b/src/Element.h
@@ -23,6 +23,11 @@ public:
*/
template <typename Type>
Element(Type _cmd) { cmd = std::make_shared<Type>(_cmd); }
+
+ /**
+ * @brief Construct a new Element object with a std::shared_ptr of ICommand.
+ * @param _cmd the ICommand to be held by this Element.
+ */
Element(std::shared_ptr<ICommand> _cmd) { cmd = _cmd; }
/**
@@ -33,9 +38,9 @@ public:
Element() {}
/**
- * @brief Get the Command pointer
+ * @brief Get the ICommand pointer
*
- * @return std::shared_ptr<Command>
+ * @return std::shared_ptr<ICommand>
*/
std::shared_ptr<ICommand> getCommand() { return cmd; }
diff --git a/src/IControlModelListener.h b/src/IControlModelListener.h
index 51c6bb9..36716a3 100644
--- a/src/IControlModelListener.h
+++ b/src/IControlModelListener.h
@@ -1,6 +1,10 @@
#pragma once
#include <string>
+/**
+ * @brief An interface to communicate strings in push communication
+ * and an update in pull communitaction.
+ */
class IControlModelListener
{
public:
diff --git a/src/ObjectFileHandler.h b/src/ObjectFileHandler.h
index d41141f..bc892ed 100644
--- a/src/ObjectFileHandler.h
+++ b/src/ObjectFileHandler.h
@@ -8,6 +8,10 @@
#include "Direction.h"
#include "Pause.h"
+/**
+ * @brief The ObjectFileHandler is used by ControlModel to read and write
+ * ICommands to and from a file.
+ */
class ObjectFileHandler
{
private:
@@ -20,11 +24,22 @@ public:
bool write(const std::vector<std::shared_ptr<ICommand>> &source);
};
+/**
+ * @brief Construct a new ObjectFileHandler, no file manipulation done here.
+ *
+ * @param _file The relative filepath to the used file.
+ */
ObjectFileHandler::ObjectFileHandler(std::string _file)
{
fileName = _file;
}
+/**
+ * @brief Write out the ICommands to the file specified in the constructor.
+ *
+ * @param source Reference of a vector filled with ICommands to be saved.
+ * @returns false if something went wrong, true on success.
+ */
bool ObjectFileHandler::write(const std::vector <std::shared_ptr<ICommand>> &source)
{
std::fstream file;
@@ -72,6 +87,12 @@ bool ObjectFileHandler::write(const std::vector <std::shared_ptr<ICommand>> &sou
return true;
}
+/**
+ * @brief Reads the file specified in the constructor, interpreting the file
+ * and appending matching ICommands to the given vector.
+ * @param destination The vector to which to append the ICommands from the file.
+ * @return false if something went wrong, true on success.
+ */
bool ObjectFileHandler::read(std::vector <std::shared_ptr<ICommand>> &destination)
{
std::fstream file;
@@ -105,6 +126,7 @@ bool ObjectFileHandler::read(std::vector <std::shared_ptr<ICommand>> &destinatio
else
{
//This shouldn't happen.
+ return false;
}
}
--
GitLab