updated core doc

Author: Skycoder42

doc/adminauthoriser.dox

@@ -1,7 +1,7 @@
 /*!
 @class QtAutoUpdater::AdminAuthoriser
 
-The AdminAuthorisers task is to run a program with elevated rigths. Since the way to archive this is different
+The AdminAuthoriser's task is to run a program with elevated rigths. Since the way to archive this is different
 on every platform, the authoriser is an interface. Because the "default" way to gain elevated privilegs is doing so
 by using a GUI, the default implementation is done in the AutoUpdaterWidgets library. If you intend to use the
 core library only, you will have to implement admin-authorisation yourself (if you require it)
@@ -24,7 +24,7 @@ instead.
 
 @param program The path to the executable. This will be an absolute path
 @param arguments A list of arguments to be passed to the executable. Can be empty
-@returns `true`, if the program could be started with <b>elevated rights</b>, `false` if not
+@returns `true`, if the program could be started with **elevated rights**, `false` if not
 
 The actual elevation and execution should be done using this function. Please note that it's possible that this function
 is called while the QCoreApplication is shutting down. If `false` is returned, no error will be shown to the user. If you want

doc/autoupdater.dox

@@ -0,0 +1,18 @@
+ /*!
+@namespace QtAutoUpdater
+
+@brief The QtAutoUpdater namespace holds all classes that are related with the updater
+
+This namespace includes both, the core library and the widgets library. Please note that
+the two are seperate libraries, that only share the namespace. The Core-Library is
+independet of the Widgets-Library and won't need a gui. The Widgets-Library requires both,
+a gui and the Core-Library.
+
+## Core-Library:
+ - Updater
+ - AdminAuthoriser
+
+## Widgets-Libray:
+ - UpdateController
+ - UpdateButton
+*/

doc/updater.dox

@@ -1,22 +1,3 @@
-/*!
-@namespace QtAutoUpdater
-
-@brief The QtAutoUpdater namespace holds all classes that are related with the updater
-
-This namespace includes both, the core library and the widgets library. Please note that
-the two are seperate libraries, that only share the namespace. The Core-Library is
-independet of the Widgets-Library and won't need a gui. The Widgets-Library requires both,
-a gui and the Core-Library.
-
-## Core-Library:
- - Updater
- - AdminAuthoriser
-
-## Widgets-Libray:
- - UpdateController
- - UpdateButton
-*/
-
 /*!
 @class QtAutoUpdater::Updater
 
@@ -25,50 +6,7 @@ evalute the results of the tool and generate update information of it. In additi
 it can schedule the maintenancetool to run in updater mode as soon as the application
 finishes. (This requires the Updater instance to exist until QCoreApplication::quit is called).
 
-## Example
-The following example shows the basic usage of the updater. Only the core library is
-required for this example. It creates a new updater instance that is connected to the
-maintenancetool located at "C:/Qt/MaintenanceTool". As soon as the application starts, it will
-check for updates and print the update result. If updates are available, their details will
-be printed and the maintenancetool is scheduled to start on exit. In both cases, the
-application will quit afterwards.
-
-@attention Since this library requires the maintenancetool that is deployed with every
-Qt Installer Framework installation, the examples cannot be tested without a
-maintenancetool! If you intend to use this library, the maintenancetool will be
-available for your final application. For testing purpose or the examples, I set the
-path to the `MaintenanceTool` that is deployed with the installation of Qt (or any
-other maintenancetool). So make shure to adjust the path if you try to run the examples.
-
-@code{.cpp}
-#include <QCoreApplication>
-#include <QDebug>
-#include <updater.h>
-
-int main(int argc, char *argv[])
-{
-	QCoreApplication a(argc, argv);
-	//create the updater with the application as parent -> will live long enough start the tool on exit
-	QtAutoUpdater::Updater *updater = new QtAutoUpdater::Updater("C:/Qt/MaintenanceTool", &a);//.exe is automatically added
-
-	QObject::connect(updater, &QtAutoUpdater::Updater::checkUpdatesDone, [updater](bool hasUpdate, bool hasError) {
-		qDebug() << "Has updates:" << hasUpdate << "\nHas errors:" << hasError;
-		if(hasUpdate) {
-			//As soon as the application quits, the maintenancetool will be started in update mode
-			updater->runUpdaterOnExit();
-			qDebug() << "Update info:" << updater->updateInfo();
-		}
-		//Quit the application
-		qApp->quit();
-	});
-
-	//start the update check
-	updater->checkForUpdates();
-	return a.exec();
-}
-@endcode
-
-@sa QtAutoUpdater::UpdateController
+@sa @ref index REAMDE.md, QtAutoUpdater::UpdateController
 */
 
 /*!
@@ -77,8 +15,8 @@ int main(int argc, char *argv[])
 @default{`./maintenancetool` on Windows/X11, `../../maintenancetool` on mac}
 
 The path of the maintenancetool has to be set inside of the constructor and cannot be
-changed later.<br>
-The path will be assumed relative to QCoreApplication::applicationDirPath(), the location
+changed later.<br/>
+The path will be resolved relative to QCoreApplication::applicationDirPath(), the location
 of the currently running application.
 
 The updater will check whether or not the given path has a file-extension. If not, it
@@ -136,36 +74,19 @@ property is the result of the last update check (if one happend).
 /*!
 @fn QtAutoUpdater::Updater::Updater(QObject *)
 
-@overload
 @param parent The object parent for QObject
 
 The maintenancetool path will be set to the default one (and cannot be changed).
 See Updater::maintenanceToolPath for more details.
 
-@overloads{
-	@ovElem{Updater(QObject *)}
-	@ovElem{Updater(const QString &, QObject *)}
-}
-
 @sa Updater::maintenanceToolPath
 */
 
 /*!
 @fn QtAutoUpdater::Updater::Updater(const QString &, QObject *)
 
-@overload
 @param maintenanceToolPath The path to the maintenancetool
-@param parent The object parent for QObject
-
-The maintenancetool path will be set to the given one (and cannot be changed).
-See Updater::maintenanceToolPath for more details.
-
-@overloads{
-	@ovElem{Updater(QObject *)}
-	@ovElem{Updater(const QString &, QObject *)}
-}
-
-@sa Updater::maintenanceToolPath
+@copydetails Updater::Updater(QObject *)
 */
 
 /*!
@@ -184,14 +105,14 @@ Updater::abortUpdateCheck to gracefully shut down the maintenancetool
 @returns `true`, if the maintenancetool finished normally, `false` if not
 
 Exiting normally does **not** mean the the update was successfull, only that the
-maintenancetool exited itself and was not killed or crashed.<br>
+maintenancetool exited itself and was not killed or crashed.<br/>
 If `false` is returned, in most cases the process either crashed or was never even
 able to start. Use Updater::errorCode to get the code. If the tool failed to start,
 it's most certanly because of an invalid path to the maintenancetool.
 
 While the updater is running, this function will always return `true`.
 
-@note Depending on the return of this function, the meaning of Updater::errorCode
+@attention Depending on the return of this function, the meaning of Updater::errorCode
 and Updater::errorLog will change!
 
 @sa Updater::running, Updater::errorCode, Updater::errorLog
@@ -202,14 +123,15 @@ and Updater::errorLog will change!
 
 @returns The exit-code of the maintenancetool or an error code
 
-@note The meaning of this functions return value depends on what Updater::exitedNormally
+@attention The meaning of this functions return value depends on what Updater::exitedNormally
 returns
 
 If the maintenancetool exited normally, this function will return the actual exit code
 of the maintenancetool. Please note that `EXIT_SUCCESS (0)` means that there are updates
-available and `EXIT_FAILURE (1)` can mean either no updates or some other kind of error.
-Please check the <a href="https://doc.qt.io/qtinstallerframework/" target="_blank">Qt Installer Framework</a>
-documentation for more details about the tool itself.
+available and `EXIT_FAILURE (1)` can mean either no updates or some other kind of error. Thus, the
+exit code is no indicator for success or failure. Please check the
+[Qt Installer Framework](https://doc.qt.io/qtinstallerframework/) documentation for more details
+about the tool itself.
 
 If the maintenancetool did not exit normally, the returned error-code will be one of
 QProcess::ProcessError.
@@ -224,14 +146,14 @@ While the updater is running, this function will always return 0.
 
 @returns The error log of the last run of the maintenancetool
 
-@note The meaning of this functions return value depends on what Updater::exitedNormally
+@attention The meaning of this functions return value depends on what Updater::exitedNormally
 returns
 
-If the maintenancetool exited normally, this function will return the cerr (standard error)
+If the maintenancetool exited normally, this function will return the stderr (standard error)
 output generated by the maintenancetool. If the maintenancetool actually fails, you
 can use this to find out why.
 
-If the maintenancetool did not exit normally, the returned error-code will be the error
+If the maintenancetool did not exit normally, the returned log will be the error
 string of the last devide error of the process, i.e. QProcess::errorString
 
 While the updater is running, this function will always return an empty QByteArray.
@@ -286,17 +208,17 @@ If `async` is `false`, this function will block and not return until the process
 terminated (or killed). If it's `true`, the function will return immediately. You can
 use Updater::running. To find out when the process actually finishes.
 
-@warning In most cases there will be no side-effects of a abort. However, if the tool has to be killed,
-this may cause unwanted effects. As an example, you may not be able to start the tool until you restart
-your system. If possible, do not abort the check, but instead just wait for it to finish.
+@warning In most cases there will be no side-effects of an abort. However, if the tool has to be killed,
+because of no delay or a timeout, this may cause unwanted effects. As an example, you may not be able to
+start the tool until you restart your system, or worst case scenario, break the installation.
+If possible, do not abort the check, but instead just wait for it to finish.
 
 @sa Updater::checkForUpdates, Updater::running, Updater::exitedNormally
 */
 
 /*!
 @fn QtAutoUpdater::Updater::scheduleUpdate(int , bool)
 
-@overload
 @param delaySeconds The time (in seconds) to wait until the update is started
 @param repeated Specifies, whether the updater should be started every `delaySeconds`
 or only once
@@ -311,18 +233,12 @@ If the updater is already running while the task is triggered, nothing will happ
 The scheduled update will only work if this same instance of the updater is still alive
 at that time.
 
-@overloads{
-	@ovElem{scheduleUpdate(int , bool)}
-	@ovElem{scheduleUpdate(const QDateTime &)}
-}
-
 @sa Updater::cancelScheduledUpdate, Updater::checkForUpdates
 */
 
 /*!
 @fn QtAutoUpdater::Updater::scheduleUpdate(const QDateTime &)
 
-@overload
 @param when The timepoint where the update should be started
 @returns The internal ID of this update task. Can be used to cancel the task
 
@@ -335,11 +251,6 @@ If the updater is already running while the task is triggered, nothing will happ
 The scheduled update will only work if this same instance of the updater is still alive
 at that time.
 
-@overloads{
-	@ovElem{scheduleUpdate(int , bool)}
-	@ovElem{scheduleUpdate(const QDateTime &)}
-}
-
 @sa Updater::cancelScheduledUpdate, Updater::checkForUpdates
 */
 
@@ -360,11 +271,10 @@ Updater::abortUpdateCheck
 /*!
 @fn QtAutoUpdater::Updater::runUpdaterOnExit(AdminAuthoriser *)
 
-@overload
 @param authoriser An optional admin authoriser instance to execture the updater as admin
 
 Schedules the maintenancetool to be run on exit. This means that as soon as the
-application exits, the updater will run the maintenancetool (with the paramter `--updater`)
+application exits, the updater will run the maintenancetool (with the default parameter `--updater`)
 detached. This way you can let the user do the actual update if you found that there
 are new updates.
 
@@ -382,30 +292,14 @@ arguments and admin authorisation, i.e. the last call to this function will dete
 how the updater starts. To cancel this (stop the maintenancetool from beeing started),
 you cann use Updater::cancelExitRun.
 
-@overloads{
-	@povElem{runUpdaterOnExit(AdminAuthoriser *)}
-	@ovElem{runUpdaterOnExit(const QStringList &, AdminAuthoriser *)}
-}
-
 @sa Updater::willRunOnExit, Updater::cancelExitRun, AdminAuthoriser
 */
 
 /*!
 @fn QtAutoUpdater::Updater::runUpdaterOnExit(const QStringList &, AdminAuthoriser *)
 
-@overload
-@param arguments The arguments to be passed to to the maintenancetool
-@param authoriser An optional admin authoriser to execture the updater as admin
-
-This overload will use custom arguments for the invokation of the maintenancetool
-instead of using `--updater`
-
-@overloads{
-	@povElem{runUpdaterOnExit(AdminAuthoriser *)}
-	@ovElem{runUpdaterOnExit(const QStringList &, AdminAuthoriser *)}
-}
-
-@sa Updater::willRunOnExit, Updater::cancelExitRun, AdminAuthoriser
+@param arguments The custom arguments to be passed to to the maintenancetool
+@copydetails Updater::runUpdaterOnExit(AdminAuthoriser *)
 */
 
 /*!
@@ -421,19 +315,18 @@ function will cancel that and nothing will happend on exit.
 @fn QtAutoUpdater::Updater::checkUpdatesDone
 
 @param hasUpdates Specifies whether or not the new updates could be found
-@param hasError `true`, if the updater did not exit normally or returned something other
-than `EXIT_SUCCESS (0)`, `false` if everything is ok
+@param hasError `true`, if the updater did not exit normally or provided invalid data, `false` if everything is ok
 
 `hasUpdates` can be used to determine if there are updates. If it is set to true, you
 can assume that Updater::updateInfo contains at least one value (but it's not guaranteed).
 
 `hasError` basically summarises the error state. If it is `false`, everything is ok. If
-it is `true`, the maintenancetool either did not finish normally or returned an error code
-different from success. You can use the error functions to find out if and what went wrong.
+it is `true`, the maintenancetool did not work properly. You can use the error functions
+to find out if and what went wrong.
 
-@note If `hasError` is true, it does not neccesarily mean that something went wrong. Since
-the maintenancetool returns `EXIT_FAILURE (1)` if no new updates are available, you will have
-to use the other functions provided to get the actual error.
+@note If `hasError` is false, it does not neccesarily mean that everything went fine. Since
+the maintenancetool returns `EXIT_FAILURE (1)` if no new updates are available, it cannot be
+used as an error indicator, you will have to use the other functions provided to get the actual error.
 
 @sa Updater::checkForUpdates, Updater::running, Updater::updateInfo, Updater::exitedNormally,
 Updater::errorCode, Updater::errorLog

src/autoupdatercore/adminauthoriser.h

@@ -13,9 +13,9 @@ namespace QtAutoUpdater
 class Q_AUTOUPDATERCORE_EXPORT AdminAuthoriser
 {
 public:
-	//! Destructor
+	//! Virtual destructor
 	virtual inline ~AdminAuthoriser() {}
-	//! Specifies whether this program already has elevated rights or not
+	//! Tests whether this program already has elevated rights or not
 	virtual bool hasAdminRights() = 0;
 	//! Runs a program with the given arguments with elevated rights
 	virtual bool executeAsAdmin(const QString &program, const QStringList &arguments) = 0;

src/autoupdatercore/updater.cpp

@@ -88,6 +88,11 @@ void Updater::cancelScheduledUpdate(int taskId)
 	d->scheduler->cancelSchedule(taskId);
 }
 
+void Updater::runUpdaterOnExit(AdminAuthoriser *authoriser)
+{
+	runUpdaterOnExit({QStringLiteral("--updater")}, authoriser);
+}
+
 void Updater::runUpdaterOnExit(const QStringList &arguments, AdminAuthoriser *authoriser)
 {
 	d->runOnExit = true;