From edda04bc5eb31ffe908a835ac2eef7cdb3ebafcc Mon Sep 17 00:00:00 2001
From: tobiglaser <76131623+tobiglaser@users.noreply.github.com>
Date: Thu, 5 May 2022 23:58:07 +0200
Subject: [PATCH] Lots of Doxygen comments + minor corrections
---
src/Command.h | 21 +++++++++++++
src/CommandListOWN.h | 70 ++++++++++++++++++++++++++++++++++++++++++--
src/Direction.h | 19 ++++++++++++
src/Element.h | 46 ++++++++++++++++++++++++++++-
src/Gear.h | 25 ++++++++++++++++
src/Pause.h | 22 +++++++++++++-
6 files changed, 198 insertions(+), 5 deletions(-)
diff --git a/src/Command.h b/src/Command.h
index 2cd4a39..42218da 100644
--- a/src/Command.h
+++ b/src/Command.h
@@ -3,12 +3,33 @@
#include "commandlib.h"
+/**
+ * @brief Base class for the specific Command implementations
+ * e.g. Gear, Direction and Pause.
+ */
class Command : ICommand
{
private:
std::string name;
public:
+ /**
+ * @brief Construct a new Command object with name _name.
+ *
+ * @param _name of the Command
+ */
Command(std::string _name) { name = _name; }
+
+ /**
+ * @brief Get the Commands name.
+ *
+ * @return std::string name
+ */
std::string getName() { return name; }
+
+ /**
+ * @brief Virtual. Implement to return a string version of the Command.
+ *
+ * @return std::string representation of the Command.
+ */
virtual std::string getConfig() = 0;
};
\ No newline at end of file
diff --git a/src/CommandListOWN.h b/src/CommandListOWN.h
index b5cde4e..4203aeb 100644
--- a/src/CommandListOWN.h
+++ b/src/CommandListOWN.h
@@ -9,7 +9,10 @@
#include "Direction.h"
#include "Pause.h"
-
+/**
+ * @brief A doubly linked List of std::shared_ptr<Element>
+ *
+ */
class CommandList
{
private:
@@ -34,6 +37,11 @@ public:
void printCommands();
};
+/**
+ * @brief Returns the number of Elements in the List
+ *
+ * @return int Elements in the List
+ */
int CommandList::getSize()
{
std::shared_ptr<Element> ptr = root;
@@ -45,6 +53,10 @@ int CommandList::getSize()
return i;
}
+/**
+ * @brief Removes every Element from the List.
+ *
+ */
void CommandList::clear()
{
std::shared_ptr<Element> current = root;
@@ -59,7 +71,14 @@ void CommandList::clear()
}
}
-template <class Type>
+/**
+ * @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
+ */
+template <typename Type>
std::shared_ptr<Command> CommandList::add(const Type _cmd)
{
std::shared_ptr<Element> newElement = std::make_shared<Element>(_cmd);
@@ -69,7 +88,10 @@ std::shared_ptr<Command> CommandList::add(const Type _cmd)
return newElement->getCommand();
}
-//clears list before adding 5 Commands
+/**
+ * @brief Clears list before adding 5 Commands to the list.
+ *
+ */
void CommandList::createCommands()
{
clear();
@@ -81,6 +103,10 @@ void CommandList::createCommands()
add(Gear(-10, 2.71));
}
+/**
+ * @brief Prints out every Command in the list to std::cout using the getConfig() method.
+ *
+ */
void CommandList::printCommands()
{
std::shared_ptr<Element> current = root;
@@ -92,6 +118,13 @@ 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
+ * or nullptr, if unsuccessful
+ */
std::shared_ptr<Command> CommandList::remove(unsigned int _pos)
{
std::shared_ptr<Element> toRemove = getElement(_pos);
@@ -109,6 +142,12 @@ std::shared_ptr<Command> CommandList::remove(unsigned int _pos)
return toRemove->getCommand();
}
+/**
+ * @brief Get the Element at _pos of the list.
+ *
+ * @param _pos Position of the wanted Element.
+ * @return std::shared_ptr<Element> to the Element at _pos or nullptr if unsuccessful.
+ */
std::shared_ptr<Element> CommandList::getElement(unsigned int _pos)
{
if (_pos > getSize())
@@ -123,6 +162,12 @@ std::shared_ptr<Element> CommandList::getElement(unsigned int _pos)
return elem;
}
+/**
+ * @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.
+ */
std::shared_ptr<Command> CommandList::getCommand(unsigned int _pos)
{
std::shared_ptr<Element> elem = getElement(_pos);
@@ -136,6 +181,12 @@ std::shared_ptr<Command> CommandList::getCommand(unsigned int _pos)
}
}
+/**
+ * @brief Searches the list for a std::shared_ptr<Command>.
+ *
+ * @param _cmd to look up.
+ * @return int position of the std::shared_ptr<Command> or -1 if unsuccessful.
+ */
int CommandList::getPos(std::shared_ptr<Command> _cmd)
{
std::shared_ptr<Element> elem = root;
@@ -153,6 +204,12 @@ int CommandList::getPos(std::shared_ptr<Command> _cmd)
return i;
}
+/**
+ * @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.
+ */
std::shared_ptr<Command> CommandList::moveUp(unsigned int _pos)
{
if (_pos <= 1)
@@ -179,6 +236,13 @@ std::shared_ptr<Command> CommandList::moveUp(unsigned int _pos)
return toReturn;
}
+/**
+ * @brief Moves down an Element in the list.
+ * 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.
+ */
std::shared_ptr<Command> CommandList::moveDown(unsigned int _pos)
{
std::shared_ptr<Element> ptr = getElement(_pos);
diff --git a/src/Direction.h b/src/Direction.h
index a7b45df..739f694 100644
--- a/src/Direction.h
+++ b/src/Direction.h
@@ -3,6 +3,10 @@
#include "Command.h"
#include <string>
+/**
+ * @brief The Direction command makes the robot turn around the set angle in place.
+ *
+ */
class Direction : public Command, public IDirection
{
private:
@@ -15,11 +19,21 @@ public:
std::string getConfig();
};
+/**
+ * @brief Construct a new Direction:: Direction Command setting its
+ * degree variable.
+ * @param newDegree, the angle to be set
+ */
Direction::Direction(int newDegree) : Command(IDirection::direction)
{
setDegree(newDegree);
}
+/**
+ * @brief Change the angle variable,
+ * clipping at -90 and +90 degrees.
+ * @param newDegree, the angle to be set
+ */
void Direction::setDegree(int newDegree)
{
if (newDegree <= -90)
@@ -30,6 +44,11 @@ void Direction::setDegree(int newDegree)
degree = newDegree;
}
+/**
+ * @brief Returns a string representation of the Command
+ * and it's value.
+ * @return std::string "Direction - Degree: ...."
+ */
std::string Direction::getConfig()
{
std::string str = IDirection::direction
diff --git a/src/Element.h b/src/Element.h
index 24f6af2..ea3953c 100644
--- a/src/Element.h
+++ b/src/Element.h
@@ -3,6 +3,10 @@
#include "Command.h"
+/**
+ * @brief Element of the doubly linked list CommandList.
+ *
+ */
class Element
{
private:
@@ -11,14 +15,54 @@ private:
std::shared_ptr<Command> cmd;
public:
- template <class Type>
+ /**
+ * @brief Construct a new Element object with a std::shared_ptr of type Type.
+ * The template function does not check if Type inherits from Command, potential bug.
+ * @tparam Type typename of _cmd is implicitly given.
+ * @param _cmd the Command to be held by this Element.
+ */
+ template <typename Type>
Element(Type _cmd) { cmd = std::make_shared<Type>(_cmd); }
+
+ /**
+ * @brief Construct an empty Element object. Dont use this constructor!
+ *
+ * @warning This is constructor is only needed when initializing the root Element of the CommandList!
+ */
Element() {}
+
+ /**
+ * @brief Get the Command pointer
+ *
+ * @return std::shared_ptr<Command>
+ */
std::shared_ptr<Command> getCommand() { return cmd; }
+ /**
+ * @brief Set the next Element
+ *
+ * @param _next to the next Element
+ */
void setNext(std::shared_ptr<Element> _next) { next = _next; }
+
+ /**
+ * @brief Get the next Element
+ *
+ * @return std::shared_ptr<Element> of the next Element
+ */
std::shared_ptr<Element> getNext() { return next; }
+ /**
+ * @brief Set the previous Element
+ *
+ * @param _prev of the previous Element
+ */
void setPrev(std::shared_ptr<Element> _prev) { prev = _prev; }
+
+ /**
+ * @brief Get the previous Element
+ *
+ * @return std::shared_ptr<Element> of the previous Element
+ */
std::shared_ptr<Element> getPrev() { return prev; }
};
\ No newline at end of file
diff --git a/src/Gear.h b/src/Gear.h
index 648cadd..50ec72c 100644
--- a/src/Gear.h
+++ b/src/Gear.h
@@ -3,6 +3,10 @@
#include "Command.h"
#include <string>
+/**
+ * @brief The Gear command makes the robot drive in a straight line
+ * with the set speed for the set time.
+ */
class Gear : public Command, public IGear
{
private:
@@ -19,12 +23,23 @@ public:
std::string getConfig();
};
+/**
+ * @brief Construct a new Gear:: Gear Command setting its variables.
+ *
+ * @param newSpeed is the speed to be set
+ * @param newDuration the time for which to drive
+ */
Gear::Gear(int newSpeed, double newDuration) : Command(IGear::gear)
{
setSpeed(newSpeed);
setDuration(newDuration);
}
+/**
+ * @brief Change the speed variable,
+ * clipping at -100 and +100.
+ * @param newSpeed the speed to be set
+ */
void Gear::setSpeed(int newSpeed)
{
if (newSpeed <= -100)
@@ -35,6 +50,11 @@ void Gear::setSpeed(int newSpeed)
speed = newSpeed;
}
+/**
+ * @brief Change the duration variable.
+ *
+ * @param newDuration the duration to be set
+ */
void Gear::setDuration(double newDuration)
{
if (newDuration < 0)
@@ -43,6 +63,11 @@ void Gear::setDuration(double newDuration)
duration = newDuration;
}
+/**
+ * @brief Returns a string representation of the Command
+ * and it's values.
+ * @return std::string "Gear - Speed: ... for: ...s"
+ */
std::string Gear::getConfig()
{
std::string str = IGear::gear
diff --git a/src/Pause.h b/src/Pause.h
index 1dbf5ba..a39058c 100644
--- a/src/Pause.h
+++ b/src/Pause.h
@@ -3,6 +3,10 @@
#include "Command.h"
#include <string>
+/**
+ * @brief The Pause command makes the robot do nothing
+ * for the set time.
+ */
class Pause : public Command, public IPause
{
private:
@@ -15,11 +19,21 @@ public:
std::string getConfig();
};
+/**
+ * @brief Construct a new Pause:: Pause Command setting its duration variable
+ *
+ * @param newDuration
+ */
Pause::Pause(double newDuration) : Command(IPause::pause)
{
setDuration(newDuration);
}
+/**
+ * @brief Change the duration variable
+ *
+ * @param newDuration
+ */
void Pause::setDuration(double newDuration)
{
if (newDuration < 0)
@@ -28,10 +42,16 @@ void Pause::setDuration(double newDuration)
duration = newDuration;
}
+/**
+ * @brief Returns a string representation of the Command
+ * and it's value.
+ * @return std::string "Pause - Duration: ...s"
+ */
std::string Pause::getConfig()
{
std::string str = IPause::pause
+ " - Duration: "
- + std::to_string(duration);
+ + std::to_string(duration)
+ + 's';
return str;
};
\ No newline at end of file
--
GitLab