From 424193706985c4968033cd2bb047a037643df08c Mon Sep 17 00:00:00 2001
From: itsmattkc <itsmattkc@gmail.com>
Date: Sun, 30 Jun 2019 12:13:00 -0700
Subject: [PATCH] license and documentation for task

---
 app/task/import/import.cpp |  20 +++++++
 app/task/import/import.h   |  20 +++++++
 app/task/probe/probe.cpp   |  20 +++++++
 app/task/probe/probe.h     |  20 +++++++
 app/task/task.cpp          |   7 +++
 app/task/task.h            | 119 +++++++++++++++++++++++++++++++++++++
 app/task/taskthread.cpp    |  20 +++++++
 app/task/taskthread.h      |  20 +++++++
 8 files changed, 246 insertions(+)

diff --git a/app/task/import/import.cpp b/app/task/import/import.cpp
index 0c10d91de..efb4b5cbc 100644
--- a/app/task/import/import.cpp
+++ b/app/task/import/import.cpp
@@ -1,3 +1,23 @@
+/***
+
+  Olive - Non-Linear Video Editor
+  Copyright (C) 2019 Olive Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
 #include "import.h"
 
 #include <QApplication>
diff --git a/app/task/import/import.h b/app/task/import/import.h
index ddfcc63a2..4ed22f9d9 100644
--- a/app/task/import/import.h
+++ b/app/task/import/import.h
@@ -1,3 +1,23 @@
+/***
+
+  Olive - Non-Linear Video Editor
+  Copyright (C) 2019 Olive Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
 #ifndef IMPORT_H
 #define IMPORT_H
 
diff --git a/app/task/probe/probe.cpp b/app/task/probe/probe.cpp
index 28f325c0b..06e644e8f 100644
--- a/app/task/probe/probe.cpp
+++ b/app/task/probe/probe.cpp
@@ -1,3 +1,23 @@
+/***
+
+  Olive - Non-Linear Video Editor
+  Copyright (C) 2019 Olive Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
 #include "probe.h"
 
 #include <QFileInfo>
diff --git a/app/task/probe/probe.h b/app/task/probe/probe.h
index 0c4a5069e..c0244aceb 100644
--- a/app/task/probe/probe.h
+++ b/app/task/probe/probe.h
@@ -1,3 +1,23 @@
+/***
+
+  Olive - Non-Linear Video Editor
+  Copyright (C) 2019 Olive Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
 #ifndef PROBE_H
 #define PROBE_H
 
diff --git a/app/task/task.cpp b/app/task/task.cpp
index 62adf3742..34e3f17f6 100644
--- a/app/task/task.cpp
+++ b/app/task/task.cpp
@@ -30,6 +30,11 @@ Task::Task() :
 
 bool Task::Start()
 {
+  // Tasks can only start if they're waiting
+  if (status_ != kWaiting) {
+    return false;
+  }
+
   // Check if this task has any dependencies (tasks that should complete before this one starts)
 
   for (int i=0;i<dependencies_.size();i++) {
@@ -104,6 +109,8 @@ void Task::set_status(const Task::Status &status)
 
 void Task::ThreadComplete()
 {
+  // thread_.result() will be set to the return value of Action()
+
   if (thread_.result()) {
     set_status(kFinished);
   } else {
diff --git a/app/task/task.h b/app/task/task.h
index c5a3c0a06..f15d58e4e 100644
--- a/app/task/task.h
+++ b/app/task/task.h
@@ -25,42 +25,158 @@
 
 #include "task/taskthread.h"
 
+/**
+ * @brief The Task class
+ *
+ * A base class for background tasks running in Olive.
+ *
+ * Tasks are multithreaded by design (i.e. they will always spawn
+ * a new thread and run in it).
+ *
+ * To subclass your own Task, override Action() and return TRUE on success or FALSE on failure. Note that a Task can
+ * provide a "negative" output and still have succeeded. For example, the ProbeTask's role is to determine whether a
+ * certain media file can be used in Olive. Even if the probe *fails* to find a Decoder for this file, the Task itself
+ * has *suceeded* at discovering this. A failure of ProbeTask would indicate a catastrophic failure meaning it was
+ * unable to determine anything about the file.
+ *
+ * Tasks should be used with the TaskManager which will manage starting and deleting them. It'll also only start as
+ * many Tasks as there are threads on the system as to not overload them.
+ *
+ * Tasks support "dependency tasks", i.e. a Task that should be complete before another Task begins.
+ */
 class Task : public QObject
 {
   Q_OBJECT
 public:
+  /**
+   * @brief The Status enum
+   *
+   * All states that a Task can be in. When subclassing, you don't need to set the Task's status as the base class
+   * does that automatically.
+   */
   enum Status {
+    /// This Task is yet to start
     kWaiting,
+
+    /// This Task is currently running (see Action())
     kWorking,
+
+    /// This Task has completed successfully
     kFinished,
+
+    /// This Task failed and could not complete
     kError
   };
 
+  /**
+   * @brief Task Constructor
+   */
   Task();
 
+  /**
+   * @brief Try to start this Task
+   *
+   * The main function for starting this Task. If this task is currently waiting, this function will start a new thread
+   * and set the status to kWorking.
+   *
+   * This function also checks its dependency Tasks and will only start if all of them are complete. If they are still
+   * working, this function will return FALSE and the status will continue to be kWaiting. If any of them failed, this
+   * Task will also fail - this function will return FALSE and the status will be set to kError.
+   *
+   * @return
+   *
+   * TRUE if the Task started, FALSE if not.
+   */
   bool Start();
 
+  /**
+   * @brief The main Task function
+   *
+   * Action() is the function that gets called once another thread has been created. This function should be overridden
+   * in subclasses.
+   *
+   * It's also recommended to emit ProgressChanged() throughout your Action() so that any attached ProgressBars can
+   * show accurate progress information.
+   *
+   * @return
+   *
+   * TRUE if the Task could complete successfully. FALSE if not. Note that FALSE should only be returned if the Task
+   * could not finish, not if the Task found a negative result (see Task documentation for details). Before returning
+   * FALSE, it's recommended to use set_error() to signal to the user what caused the failure.
+   */
   virtual bool Action();
 
+  /**
+   * @brief Current status of the Task
+   *
+   * @return
+   *
+   * A member of the Task::Status enum.
+   */
   const Status& status();
 
+  /**
+   * @brief Retrieve the current title of this Task
+   */
   const QString& text();
 
+  /**
+   * @brief Retrieve the current error message (empty if no error)
+   */
   const QString& error();
 
+  /**
+   * @brief Add a dependency Task
+   *
+   * If another Task needs to complete before this one can begin, it can be added as a "dependency task". If a task
+   * has dependencies, Start() will not start the task until the dependency tasks have all completed. If any of the
+   * dependency tasks fail, this Task will also fail before starting.
+   *
+   * Dependencies can only be added if the Task is kWaiting.
+   *
+   * @param dependency
+   */
   void AddDependency(Task* dependency);
 
 protected:
+  /**
+   * @brief Set the error message
+   *
+   * It is recommended to use this if your Action() function ever returns FALSE to tell the user why the failure
+   * occurred.
+   */
   void set_error(const QString& s);
 
+  /**
+   * @brief Set the Task title
+   *
+   * Used in the UI Task Manager to distinguish Tasks from each other. Generally this should be set in the constructor
+   * and shouldn't need to change during the life of the Task. To show an error message, it's recommended to use
+   * set_error() instead.
+   */
   void set_text(const QString& s);
 
 signals:
+  /**
+   * @brief Signal emitted whenever the Task status changes
+   */
   void StatusChanged(Task::Status s);
 
+  /**
+   * @brief Signal emitted whenever progress is made
+   *
+   * Emit this throughout Action() to update any attached ProgressBars on the progress of this Task.
+   *
+   * @param p
+   *
+   * A value (percentage) between 0 and 100.
+   */
   void ProgressChanged(int p);
 
 private:
+  /**
+   * @brief Set the status of this Task (also emits StatusChanged())
+   */
   void set_status(const Status& status);
 
   Status status_;
@@ -74,6 +190,9 @@ private:
   QList<Task*> dependencies_;
 
 private slots:
+  /**
+   * @brief A slot when the inner thread completes either successfully or unsuccessfully
+   */
   void ThreadComplete();
 };
 
diff --git a/app/task/taskthread.cpp b/app/task/taskthread.cpp
index 399f35dbb..234fbf8ef 100644
--- a/app/task/taskthread.cpp
+++ b/app/task/taskthread.cpp
@@ -1,3 +1,23 @@
+/***
+
+  Olive - Non-Linear Video Editor
+  Copyright (C) 2019 Olive Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
 #include "taskthread.h"
 
 #include "task/task.h"
diff --git a/app/task/taskthread.h b/app/task/taskthread.h
index 983b6dcac..7fff196fd 100644
--- a/app/task/taskthread.h
+++ b/app/task/taskthread.h
@@ -1,3 +1,23 @@
+/***
+
+  Olive - Non-Linear Video Editor
+  Copyright (C) 2019 Olive Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
 #ifndef TASKTHREAD_H
 #define TASKTHREAD_H