Comment C++ files

TODO.md

@@ -37,9 +37,9 @@
   - Use new default/reset controls system 
 - Split `HScrollableTextArea`
 - Composer
-- Missing room keybinds (invite, etc), and don't put all the binds in 
-  one central file (else we can only rely on uiState properties)
-- Use QML states
+- Don't put all the binds in one central file
+  - Missing room keybinds (invite, etc) and close failed upload
+- Use QML states?
 - Try gel for the models and stop being lazy in python
 
 - Room Sidepane save/load size & keybinds
@@ -71,6 +71,8 @@
 - Don't store states in delegates
 - [hr not working](https://bugreports.qt.io/browse/QTBUG-74342)
 - Terrible performance using `QT_QPA_PLATFORM=wayland-egl`, must use `xcb`
+- Can't use `QQmlApplicationEngine`, problem with QApplication?
+  See https://bugreports.qt.io/browse/QTBUG-50992
 
 ## Interface
 

src/clipboard.cpp

@@ -1,3 +1,5 @@
+// Function implementations of the Clipboard class, see the clipboard.h file.
+
 #include <QClipboard>
 #include "clipboard.h"
 
@@ -17,6 +19,7 @@ QString Clipboard::text() const {
     return m_clipboard->text(QClipboard::Clipboard);
 }
 
+
 void Clipboard::setText(const QString &text) {
     m_clipboard->setText(text, QClipboard::Clipboard);
 }
@@ -26,6 +29,7 @@ QString Clipboard::selection() const {
     return m_clipboard->text(QClipboard::Selection);
 }
 
+
 void Clipboard::setSelection(const QString &text) {
     if (m_clipboard->supportsSelection()) {
         m_clipboard->setText(text, QClipboard::Selection);

src/clipboard.h

@@ -1,3 +1,6 @@
+// The Clipboard class exposes system clipboard management and retrieval
+// to QML.
+
 #ifndef CLIPBOARD_H
 #define CLIPBOARD_H
 
@@ -17,9 +20,11 @@ class Clipboard : public QObject
 public:
     explicit Clipboard(QObject *parent = 0);
 
+    // Normal primary clipboard
     QString text() const;
     void setText(const QString &text);
 
+    // X11 select-middle-click-paste clipboard
     QString selection() const;
     void setSelection(const QString &text);
 

src/main.cpp

@@ -1,3 +1,6 @@
+// This file creates the application, registers custom objects for QML
+// and launches Window.qml (the root component).
+
 #include <QApplication>
 #include <QQmlEngine>
 #include <QQmlContext>
@@ -11,35 +14,47 @@
 
 
 int main(int argc, char *argv[]) {
+    // Define some basic info about the app before creating the QApplication
     QApplication::setOrganizationName("harmonyqml");
     QApplication::setApplicationName("harmonyqml");
     QApplication::setApplicationDisplayName("HarmonyQML");
     QApplication::setApplicationVersion("0.2.3");
     QApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
-
     QApplication app(argc, argv);
 
+    // Create the QML engine and get the root context.
+    // We will add it some properties that will be available globally in QML.
     QQmlEngine engine;
     QQmlContext *objectContext = new QQmlContext(engine.rootContext());
 
+    // Set the debugMode properties depending of if we're running in debug mode
+    // or not (`qmake CONFIG+=dev ...`, default in live-reload.sh)
 #ifdef QT_DEBUG
     objectContext->setContextProperty("debugMode", true);
 #else
     objectContext->setContextProperty("debugMode", false);
 #endif
 
+    // Add our custom non-visual `QObject `s as properties.
+    // Their attributes and methods will be accessing like normal QML objects.
     objectContext->setContextProperty("CppUtils", new Utils());
     objectContext->setContextProperty("Clipboard", new Clipboard());
 
+    // Register our custom visual items that will be importable from QML,
+    // e.g. `import RadialBar 1.0`
     qmlRegisterType<RadialBar>("RadialBar", 1, 0, "RadialBar");
 
+    // Create the QML root component by loading its file from the Qt Resource
+    // System (qrc:/, resources stored in the app's executable) if possible,
+    // else fall back to the filesystem.
+    // The dev qmake flag disables the resource system for faster builds.
     QFileInfo qrcPath(":src/qml/Window.qml");
-
     QQmlComponent component(
         &engine,
         qrcPath.exists() ? "qrc:/src/qml/Window.qml" : "src/qml/Window.qml"
     );
     component.create(objectContext);
 
+    // Finally, execute the app. Return its system exit code when it exits.
     return app.exec();
 }

src/utils.cpp

@@ -1,3 +1,5 @@
+// Function implementations of the Utils class, see the utils.h file.
+
 #include <QLocale>
 #include <QUuid>
 
@@ -6,14 +8,14 @@
 
 Utils::Utils() {
     // Initialization
-};
+}
 
 
 QString Utils::formattedBytes(qint64 bytes, int precision) {
     return m_locale.formattedDataSize(
         bytes, precision, QLocale::DataSizeTraditionalFormat
     );
-};
+}
 
 
 QString Utils::uuid() {

src/utils.h

@@ -1,3 +1,6 @@
+// The Utils class exposes various useful functions for QML that aren't
+// normally provided by Qt.
+
 #ifndef UTILS_H
 #define UTILS_H