Updater: Added missing comment banners; removed context help buttons

There is now a common base class for all the updater dialogs, where the
context help button is removed.

doomsday/engine/engine.pro

@@ -364,6 +364,7 @@ DENG_HEADERS += \
     portable/include/zipfile.h \
     portable/src/updater/downloaddialog.h \
     portable/src/updater/updateavailabledialog.h \
+    portable/src/updater/updaterdialog.h \
     portable/src/updater/updatersettings.h \
     portable/src/updater/updatersettingsdialog.h \
     portable/src/updater/versioninfo.h
@@ -644,6 +645,7 @@ SOURCES += \
     portable/src/updater.cpp \
     portable/src/updater/downloaddialog.cpp \
     portable/src/updater/updateavailabledialog.cpp \
+    portable/src/updater/updaterdialog.cpp \
     portable/src/updater/updatersettings.cpp \
     portable/src/updater/updatersettingsdialog.cpp \
     portable/src/uri.c \

doomsday/engine/portable/include/updater.h

@@ -20,6 +20,11 @@
  * 02110-1301 USA</small>
  */
 
+/**
+ * @defgroup updater
+ * Automatic updater
+ */
+
 #ifndef LIBDENG_UPDATER_H
 #define LIBDENG_UPDATER_H
 

doomsday/engine/portable/src/updater/downloaddialog.cpp

@@ -1,3 +1,25 @@
+/**
+ * @file downloaddialog.cpp
+ * Dialog that downloads a distribution package. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
 #include "downloaddialog.h"
 #include "updatersettings.h"
 #include <QNetworkAccessManager>
@@ -96,7 +118,7 @@ struct DownloadDialog::Instance
 };
 
 DownloadDialog::DownloadDialog(de::String downloadUri, de::String fallbackUri, QWidget *parent)
-    : QDialog(parent)
+    : UpdaterDialog(parent)
 {
     d = new Instance(this, downloadUri, fallbackUri);
 }

doomsday/engine/portable/src/updater/downloaddialog.h

@@ -1,9 +1,31 @@
-#ifndef DOWNLOADDIALOG_H
-#define DOWNLOADDIALOG_H
+/**
+ * @file downloaddialog.h
+ * Dialog that downloads a distribution package. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
+#ifndef LIBDENG_DOWNLOADDIALOG_H
+#define LIBDENG_DOWNLOADDIALOG_H
 
 #ifdef __cplusplus
 
-#include <QDialog>
+#include "updaterdialog.h"
 #include <de/String>
 
 class QNetworkReply;
@@ -12,7 +34,7 @@ class QNetworkReply;
  * Dialog for downloading an update in the background and then starting
  * the (re)installation process.
  */
-class DownloadDialog : public QDialog
+class DownloadDialog : public UpdaterDialog
 {
     Q_OBJECT
 
@@ -54,4 +76,4 @@ int Updater_IsDownloadInProgress(void);
 } // extern "C"
 #endif
 
-#endif // DOWNLOADDIALOG_H
+#endif // LIBDENG_DOWNLOADDIALOG_H

doomsday/engine/portable/src/updater/updateavailabledialog.cpp

@@ -1,3 +1,25 @@
+/**
+ * @file updateavailabledialog.cpp
+ * Dialog for notifying the user about available updates. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
 #include "updateavailabledialog.h"
 #include "updatersettings.h"
 #include "updatersettingsdialog.h"
@@ -61,7 +83,6 @@ struct UpdateAvailableDialog::Instance
 #ifndef MACOSX
         self->setWindowTitle(tr("Doomsday %1").arg(VersionInfo().asText()));
 #endif
-        self->setWindowFlags(self->windowFlags() & ~Qt::WindowContextHelpButtonHint);
 
         emptyResultPage = true;
         stack = new QStackedLayout(self);
@@ -202,14 +223,14 @@ struct UpdateAvailableDialog::Instance
     }
 };
 
-UpdateAvailableDialog::UpdateAvailableDialog(QWidget *parent) : QDialog(parent)
+UpdateAvailableDialog::UpdateAvailableDialog(QWidget *parent) : UpdaterDialog(parent)
 {
     d = new Instance(this);
 }
 
 UpdateAvailableDialog::UpdateAvailableDialog(const VersionInfo& latestVersion, de::String changeLogUri,
                                              QWidget *parent)
-    : QDialog(parent)
+    : UpdaterDialog(parent)
 {
     d = new Instance(this, latestVersion);
     d->changeLog = changeLogUri;

doomsday/engine/portable/src/updater/updateavailabledialog.h

@@ -1,10 +1,32 @@
+/**
+ * @file updateavailabledialog.h
+ * Dialog for notifying the user about available updates. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
 #ifndef LIBDENG_UPDATEAVAILABLEDIALOG_H
 #define LIBDENG_UPDATEAVAILABLEDIALOG_H
 
-#include <QDialog>
+#include "updaterdialog.h"
 #include "versioninfo.h"
 
-class UpdateAvailableDialog : public QDialog
+class UpdateAvailableDialog : public UpdaterDialog
 {
     Q_OBJECT
 

doomsday/engine/portable/src/updater/updaterdialog.cpp

@@ -0,0 +1,28 @@
+/**
+ * @file updaterdialog.cpp
+ * Common base class for the updater dialogs. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
+#include "updaterdialog.h"
+
+UpdaterDialog::UpdaterDialog(QWidget *parent) : QDialog(parent)
+{
+    // This will remove the "?" context help button in Windows.
+    setWindowFlags(windowFlags() & ~Qt::WindowContextHelpButtonHint);
+}

doomsday/engine/portable/src/updater/updaterdialog.h

@@ -0,0 +1,38 @@
+/**
+ * @file updaterdialog.h
+ * Common base class for the updater dialogs. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
+#ifndef LIBDENG_UPDATERDIALOG_H
+#define LIBDENG_UPDATERDIALOG_H
+
+#include <QDialog>
+
+/**
+ * Base class for all the updater dialogs.
+ */
+class UpdaterDialog : public QDialog
+{
+    Q_OBJECT
+
+public:
+    explicit UpdaterDialog(QWidget *parent = 0);
+};
+
+#endif // UPDATERDIALOG_H

doomsday/engine/portable/src/updater/updatersettings.cpp

@@ -1,3 +1,28 @@
+/**
+ * @file updatersettings.cpp
+ * Persistent settings for automatic updates. @ingroup updater
+ *
+ * @todo  There should be a unified persistent configuration subsystem that
+ * combines the characteristics of QSettings and console variables.
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
 #include "updatersettings.h"
 #include "versioninfo.h"
 #include <QDateTime>

doomsday/engine/portable/src/updater/updatersettings.h

@@ -1,16 +1,45 @@
+/**
+ * @file updatersettings.h
+ * Persistent settings for automatic updates. @ingroup updater
+ *
+ * @todo  There should be a unified persistent configuration subsystem that
+ * combines the characteristics of QSettings and console variables.
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
 #ifndef LIBDENG_UPDATERSETTINGS_H
 #define LIBDENG_UPDATERSETTINGS_H
 
 #include <de/Time>
 #include <de/String>
 
+/**
+ * Convenient interface to the Updater settings. All changes to the settings
+ * are immediately saved persistently.
+ */
 class UpdaterSettings
 {
 public:
     enum Frequency
     {
         Daily     = 0,
-        Biweekly  = 1,   // 3.5 days
+        Biweekly  = 1,   // Tuesday + Saturday
         Weekly    = 2,   // 7 days
         Monthly   = 3,   // 30 days
         AtStartup = 4

doomsday/engine/portable/src/updater/updatersettingsdialog.cpp

@@ -1,3 +1,25 @@
+/**
+ * @file updatersettingsdialog.cpp
+ * Dialog for configuring automatic updates. @ingroup updater
+ *
+ * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>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 2 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, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
+ */
+
 #include "updatersettingsdialog.h"
 #include "updatersettings.h"
 #include <QDesktopServices>
@@ -34,7 +56,6 @@ struct UpdaterSettingsDialog::Instance
 
     Instance(UpdaterSettingsDialog* dlg) : self(dlg)
     {
-        self->setWindowFlags(self->windowFlags() & ~Qt::WindowContextHelpButtonHint);
         self->setWindowTitle(tr("Updater Settings"));
 
         QVBoxLayout* mainLayout = new QVBoxLayout;
@@ -141,7 +162,7 @@ struct UpdaterSettingsDialog::Instance
 };
 
 UpdaterSettingsDialog::UpdaterSettingsDialog(QWidget *parent)
-    : QDialog(parent)
+    : UpdaterDialog(parent)
 {
     d = new Instance(this);
 }