diff --git a/src/algoThread.h b/src/algoThread.h index 813c81764619f2c8845b0b92f2a4d5478a469e8b..49689c7afc35a26e529d77175a931b66f8977bf8 100644 --- a/src/algoThread.h +++ b/src/algoThread.h @@ -5,14 +5,34 @@ #include <QThread> - +/** + * @brief A QThread, specialized to run the user provided algorithm. + * QThread allows Control and CuteControl to communicate with Qt signals across the threads. + * CuteControl has to be pushed/moved to the event loop of this thread for that to work. + * It is pushed/moved back to the main thread before this thread ends. + */ class AlgoThread : public QThread { private: - void (*func)(); + void (*func)(); ///< Pointer to the function, that will be executed by the Thread. public: + /** + * @brief Set the function pointer to be executed in run(). + * + * @param algorithm + */ void setAlgorithm(void (*algorithm)()) { func = algorithm; } + /** + * For some cute functions it is necessary that the thread can receive signals from the main thread. + * E.g. cute::ok() and cute::verbosity(). + * For this to work, the CuteControl, has to be "moved to" to the event loop of this thread. + * This moving can only be done via pushing, not pulling. + * Thus, before the thread ends, the CuteControl must be pushed back to the main thread + * + * @brief Executed by QThread::start(). Executes the provided function and moves the CuteControl back to the main + * thread. + */ void run() override { func(); diff --git a/src/configPanel.h b/src/configPanel.h index c8e3513cce99c7427b7df8af55455bf714470ee0..b4049321a46d93cf07ea203f2770e708bd80ea03 100644 --- a/src/configPanel.h +++ b/src/configPanel.h @@ -9,26 +9,30 @@ #include <QSpinBox> #include <QStackedWidget> - +/** + * @brief Responsible for controlling the users Algorithms and generating the Problem. + * This is a Dockwidget, so it could be moved around or locked in place. + * + */ class ConfigPanel : public QDockWidget { Q_OBJECT private: - std::vector<QPushButton*> lockButtons; + std::vector<QPushButton*> lockButtons; ///< Holds Buttons used to prohibit changing the generated Problem. public: - QPushButton* runButton; - QPushButton* openButton; - QLineEdit* fileLine; - QPlainTextEdit* pasteBox; - QComboBox* algoBox; - QSpinBox* problemSizeBox; - QComboBox* verbosityBox; - QStackedWidget* stackedWidget; - QWidget* fileWidget; - QWidget* randomWidget; - QWidget* pasteWidget; + QPushButton* runButton; ///< Used to Start and Stop the Algorithm. + QPushButton* openButton; ///< Used to Select a File via QFileDialog. + QLineEdit* fileLine; ///< Shows path and filename and allows editing it. + QPlainTextEdit* pasteBox; ///< Used to enter csv data via drag n drop or copy and paste. + QComboBox* algoBox; ///< Used to select one of the Algorithms registered with cute::registerAlgorithm(). + QSpinBox* problemSizeBox; ///< Used to adjust the number of randomly generated Points. + QComboBox* verbosityBox; ///< Used to set the verbosity, the users code should exhibit. + QStackedWidget* stackedWidget; ///< Holds the different problem generation Widgets. + QWidget* fileWidget; ///< Holds Widgets to read a Problem from a File. + QWidget* randomWidget; ///< Holds Widgets to generate random Problems. + QWidget* pasteWidget; ///< Holds Widgets to read Problem from dragged or pasted Text. public: explicit ConfigPanel(QWidget* parent = nullptr); @@ -42,8 +46,8 @@ public slots: void setGenUnlocked(); signals: - void previewButtonClicked(); - void lockButtonClicked(); + void previewButtonClicked(); ///< Signal emitted, when one of the Preview Buttons was clicked. + void lockButtonClicked(); ///< Signal emitted, when one of the Lock/Unlock buttons was clicked. }; #endif // CONFIGPANEL_H diff --git a/src/csvParser.h b/src/csvParser.h index 8750f7e8038702761c8214cc1a94ef1366d9df7c..bf991eb0f09452018ba1816f9968400bad748abd 100644 --- a/src/csvParser.h +++ b/src/csvParser.h @@ -24,10 +24,26 @@ Below is the complete, self-contained code: #include <limits> #include <cmath> // For std::isnan +/** + * @brief Kindly provided by Copilot, this can parse a .csv File into std::strings and further into floats. + * + */ class CSVParser { public: +/** + * @brief Construct a new CSVParser object + * + * @param delimiter Char that seperates the values. Default: COMMA Seperated Values + */ CSVParser(char delimiter = ',') : delimiter(delimiter) {} + /** + * @brief Opens a filestream and passes it to parseStream() to do the actual parsing. + * + * @param filename The /path/to/file.csv to parse. + * @return false if the File could not be opened. + * @return true otherwise. + */ bool parseFile(const std::string& filename) { std::ifstream file(filename); if (!file.is_open()) { @@ -39,18 +55,32 @@ public: return true; } + /** + * @brief Creates a stringstream from the input string and passes it to parseStream() to do the actual parsing. + * + * @param rawInput The string to be parsed. + */ void parseString(const std::string& rawInput) { std::istringstream input(rawInput); parseStream(input); } - // Returns the parsed CSV data as a vector of rows containing strings. + /** + * @brief Get the whole parsed CSV data as strings. + * + * @return The parsed CSV data as a vector of rows containing strings. + */ const std::vector<std::vector<std::string>>& getRows() const { return rows; } - // Converts each field from the CSV to a float. - // Fields that cannot be converted are represented by NaN (Not a Number). + /** + * @brief Converts each field from the already parsed CSV to a float. + * Fields that cannot be converted are represented by NaN (Not a Number). + * parseString() or parseFile() have to be called before this function so that rows is populated. + * + * @return The parsed CSV data as a vector of rows containing floats. NaN for invalid fields. + */ std::vector<std::vector<float>> getFloatRows() const { std::vector<std::vector<float>> floatRows; for (const auto& row : rows) { @@ -73,9 +103,14 @@ public: } private: - char delimiter; - std::vector<std::vector<std::string>> rows; - + char delimiter; ///< Char that separates the values. + std::vector<std::vector<std::string>> rows; ///< Holds the strings, parsed from the file. + + /** + * @brief Splits the stream into lines, passes them to parseLine() and stores the result in rows. + * + * @param input The stream to be parsed. + */ void parseStream(std::istream& input) { rows.clear(); // Ensure that rows is empty before starting. @@ -86,8 +121,13 @@ private: } } - // Helper function that parses a single line of CSV. - // It supports quoted fields and the basic escaping of quotes by doubling (""). + /** + * @brief Helper function that parses a single line of CSV. + * It supports quoted fields and the basic escaping of quotes by doubling (""). + * + * @param line The line to be parsed. + * @return A vector of the parsed values as strings. + */ std::vector<std::string> parseLine(const std::string& line) { std::vector<std::string> tokens; std::string token; @@ -127,6 +167,11 @@ private: } }; #ifdef TESTING_CSV +/** + * @brief Only used to test the CSVParser. + * + * @return 0 + */ int main() { // Create an instance of CSVParser with skipHeader enabled. // Replace "example.csv" with your CSV file. diff --git a/src/csvWriter.h b/src/csvWriter.h index 1ffbf791040f6d87e3e50a6aebfe5df93d44f172..c9285aac03d260f7e209afb4e02f07ae5649311d 100644 --- a/src/csvWriter.h +++ b/src/csvWriter.h @@ -6,21 +6,38 @@ #include <fstream> #include <string> +/** + * @brief Complement to CSVParser, this class can write Points to a .csv File. + * + */ class csvWriter { private: - std::string _path; + std::string _path; ///< /path/to/file.csv to be written. public: csvWriter(std::string path); bool write(const std::vector<cute::Point>& points); }; +/** + * @brief Construct a new csvWriter object + * + * @param path The /path/to/file.csv to be written. + */ csvWriter::csvWriter(std::string path) { _path = path; } +/** + * @brief Writes a line representing "{x}, {y}\n" for each Point. + * Uses default settings to convert the floats to strings. + * + * @param points The data to be written. + * @return true if no error occured. + * @return false if an erron occured. + */ bool csvWriter::write(const std::vector<cute::Point>& points) { std::ofstream outFile(_path); diff --git a/src/cute.cpp b/src/cute.cpp index acf0ec97bed9c4044631ae01315f34a65586fb10..defb4cb6029612f3bbd7a77cb95f2ba9a83c398d 100644 --- a/src/cute.cpp +++ b/src/cute.cpp @@ -5,8 +5,20 @@ #include <chrono> +/** + * @brief This namespace allows the Timer functions to have a state without a class/object representation. + * Since it is defined in cute.cpp, + * it is only visible in this translation unit and thus hidden from the cute User. + */ namespace timer { + /** + * Each cute function pauses and resumes the timer automatically. + * The user can also pause and resume the Timer manually for a more accurate result. + * internallyPaused is used to not automatically resume a manually paused Timer. + * + * @brief Represents the different states the Timer can be in. + */ enum State { off, @@ -14,9 +26,10 @@ namespace timer paused, internallyPaused }; - std::chrono::time_point<std::chrono::high_resolution_clock, std::chrono::high_resolution_clock::duration> start; - std::chrono::microseconds duration; - State state; + std::chrono::time_point<std::chrono::high_resolution_clock, std::chrono::high_resolution_clock::duration> + start; ///< Point in Time the Timer was last started or resumed. + std::chrono::microseconds duration; ///< Accumulated duration that the Timer has run, updated by cute::TimerPause(). + State state; ///< The current state of the Timer. } //namespace timer