Flush out documentation

.github/actions/web/action.yaml

@@ -27,11 +27,11 @@ runs:
     - name: Build website
       shell: bash
       run: cd web && make prod
-    - name: Generate liboxide docs
-      shell: bash
-      run: |
-        cd shared/liboxide && make prod
     - name: Generate libblight docs
       shell: bash
       run: |
         cd shared/libblight && make prod
+    - name: Generate liboxide docs
+      shell: bash
+      run: |
+        cd shared/liboxide && make prod

shared/libblight/Doxyfile

@@ -13,8 +13,13 @@ HTML_EXTRA_FILES = ../doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \
                    ../doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js \
                    ../doxygen-awesome-css/doxygen-awesome-paragraph-link.js
 HTML_HEADER = ../doxygen-header.html
-PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED += IN_DOXYGEN
 HIDE_UNDOC_MEMBERS = YES
 HIDE_UNDOC_CLASSES = YES
 MACRO_EXPANSION = YES
 EXAMPLE_PATH = examples
+GENERATE_TAGFILE = html/libblight.tag
+ALLEXTERNALS = Yes
+ALIASES = "accessors=\par Accessors:^^"
+ALIASES += "notifier=\par Notifier signal:^^"

shared/libblight/connection.h

@@ -100,6 +100,7 @@ namespace Blight {
          * \param type Type of message
          * \param data Data to send
          * \param size Size of data
+         * \param __ackid Unique identifier to use, will automatically generate if set to 0
          * \return ack_ptr_t if the message was sent
          */
         maybe_ackid_ptr_t send(MessageType type, data_t data, size_t size, unsigned int __ackid = 0);

shared/libblight/libblight.h

@@ -9,6 +9,9 @@
 #include "connection.h"
 #include <optional>
 
+/*!
+ * \brief Blight namespace
+ */
 namespace Blight{
     /*!
      * \brief Connect to DBus

shared/libblight/libblight.pro

@@ -75,3 +75,6 @@ QMAKE_PKGCONFIG_PREFIX = /opt
 QMAKE_PKGCONFIG_LIBDIR = /opt/lib
 QMAKE_PKGCONFIG_INCDIR = /opt/include
 QMAKE_PKGCONFIG_DESTDIR = pkgconfig
+
+DISTFILES += \
+    Doxyfile

shared/liboxide/Doxyfile

@@ -13,8 +13,14 @@ HTML_EXTRA_FILES = ../doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \
                    ../doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js \
                    ../doxygen-awesome-css/doxygen-awesome-paragraph-link.js
 HTML_HEADER = ../doxygen-header.html
-PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
+PREDEFINED += IN_DOXYGEN
 HIDE_UNDOC_MEMBERS = YES
 HIDE_UNDOC_CLASSES = YES
 MACRO_EXPANSION = YES
 EXAMPLE_PATH = examples
+GENERATE_TAGFILE = html/liboxide.tag
+ALLEXTERNALS = Yes
+TAGFILES = ../libblight/html/libblight.tag=../libblight/
+ALIASES += "accessors=\par Accessors:^^"
+ALIASES += "notifier=\par Notifier signal:^^"

shared/liboxide/dbus.h

@@ -10,7 +10,61 @@
 // This must be here to make precompiled headers happy
 #ifndef LIBOXIDE_DBUS_H
 #define LIBOXIDE_DBUS_H
-
+#ifdef IN_DOXYGEN
+/*!
+ * \brief System service DBus interfaces
+ */
+namespace codes::eeems::oxide1{
+    /*!
+     * \brief General API interface
+     */
+    class General : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Power class
+     */
+    class Power : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Wifi class
+     */
+    class Wifi : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Network class
+     */
+    class Network : public QDBusAbstractInterface{};
+    /*!
+     * \brief The BSS class
+     */
+    class BSS : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Apps class
+     */
+    class Apps : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Application class
+     */
+    class Application : public QDBusAbstractInterface{};
+    /*!
+     * \brief The System class
+     */
+    class System : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Screen class
+     */
+    class Screen : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Screenshot class
+     */
+    class Screenshot : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Notifications class
+     */
+    class Notifications : public QDBusAbstractInterface{};
+    /*!
+     * \brief The Notification class
+     */
+    class Notification : public QDBusAbstractInterface{};
+}
+#endif
 #include "dbusservice_interface.h"
 #include "powerapi_interface.h"
 #include "wifiapi_interface.h"
@@ -23,8 +77,17 @@
 #include "screenshot_interface.h"
 #include "notificationapi_interface.h"
 #include "notification_interface.h"
-
+#ifdef IN_DOXYGEN
+/*!
+ * \brief Display server DBus interfaces
+ */
+namespace codes::eeems::blight1{
+    /*!
+     * \brief Display server compositor API
+     */
+    class Compositor : public QDBusAbstractInterface{};
+}
+#endif
 #include "blight_interface.h"
-
 #endif // LIBOXIDE_DBUS_H
 /*! @} */

shared/liboxide/debug.h

@@ -23,7 +23,7 @@
 /*!
  * \def __RIGHT_HERE__
  * \brief Log the current file and line number
- * \note This is only available if DEBUG is defined
+ * \note This will only do anything if DEBUG is defined
  */
 #ifdef __RIGHT_HERE__
 #undef __RIGHT_HERE__
@@ -95,9 +95,9 @@ namespace Oxide {
     /*!
      * \brief Get a formatted debug information string
      * \note this is automatically included in O_DEBUG, O_WARNING, O_INFO, and O_EVENT
-     * \param Name of file
-     * \param Line number in file
-     * \param Function information
+     * \param file Name of file
+     * \param line Line number in file
+     * \param function Function information
      * \return Formatted debug location string
      */
     LIBOXIDE_EXPORT std::string getDebugLocation(const char* file, unsigned int line, const char* function);
@@ -109,7 +109,7 @@ namespace Oxide {
     LIBOXIDE_EXPORT bool debugEnabled();
     /*!
      * \brief Get the name of the application
-     * \param Don't use qApp's application name
+     * \param ignoreQApp Don't use qApp's application name
      * \return The name of the application
      */
     LIBOXIDE_EXPORT std::string getAppName(bool ignoreQApp);

shared/liboxide/devicesettings.h

@@ -101,7 +101,7 @@ namespace Oxide{
         QString getTimezone();
         /*!
          * \brief Set the current timezone
-         * \param locale Timezone to set
+         * \param timezone Timezone to set
          */
         void setTimezone(const QString& timezone);
         /*!

shared/liboxide/event_device.h

@@ -17,74 +17,98 @@
 using namespace std;
 namespace Oxide {
     /*!
-     * \brief The event_device class
+     * \brief A class to simplify managing a /dev/event* file
      */
     class LIBOXIDE_EXPORT event_device {
     public:
+        /*!
+         * \brief Create an input_event
+         * \param type Input event type
+         * \param code Input event code
+         * \param value Input event value
+         * \return
+         */
         static input_event create_event(ushort type, ushort code, int value);
         /*!
-         * \brief event_device
-         * \param path
-         * \param flags
+         * \brief Instantiate a new instance
+         * \param path Path to the event device
+         * \param flags Flags to use when opening the event device
          */
         event_device(const string& path, int flags);
+        /*!
+         * \brief Create a copy of an event_device instance
+         * \param other Instance to copy
+         */
         event_device(const event_device& other);
         ~event_device();
         /*!
-         * \brief close
+         * \brief Close the event device
+         * \sa open()
          */
         void close();
         /*!
-         * \brief open
+         * \brief Open the event device
+         * \sa fd, error, close()
          */
         void open();
         /*!
-         * \brief lock
-         * \return
+         * \brief Grab all input from this device
+         * \return If grabbing was successful
+         * \retval 0 Successfully grabbed all input
+         * \retval EBUSY The event device is grabbed by another process
+         * \sa locked unlock()
          */
         int lock();
         /*!
-         * \brief unlock
-         * \return
+         * \brief Ungrab all input from this device
+         * \return If ungrabbing was successful
+         * \retval 0 Successfully ungrabbed all input
+         * \sa locked, lock()
          */
         int unlock();
         /*!
-         * \brief write
-         * \param ie
+         * \brief Write an input event to the event device
+         * \param ie Input event to write
+         * \sa write(ushort, ushort, int)
          */
         void write(input_event ie);
         /*!
-         * \brief write_event
-         * \param device
-         * \param type
-         * \param code
-         * \param value
+         * \brief Write an input event to the event device
+         * \param type Input event type
+         * \param code Input event code
+         * \param value Input event value
+         * \sa write(input_event)
          */
         void write(ushort type, ushort code, int value);
         /*!
-         * \brief ev_syn
+         * \brief Write an EV_SYN SYN_REPORT event to the event device
          */
         void ev_syn();
         /*!
-         * \brief ev_dropped
+         * \brief Write an EV_SYN SYN_DROPPED event to the event device
          */
         void ev_dropped();
         /*!
-         * \brief error
+         * \brief Errno reported when opening the event device
+         * \sa open()
          */
         int error;
         /*!
-         * \brief fd
+         * \brief File descriptor returned when opening the event device
+         * \sa open(), close()
          */
         int fd;
         /*!
-         * \brief device
+         * \brief Path to the event device
+         * \sa event_device(const string&, int)
          */
         string device;
         /*!
-         * \brief locked
+         * \brief If input is currently grabbed
+         * \sa lock(), unlock()
          */
         bool locked = false;
+
     private:
         int flags;
     };

shared/liboxide/eventfilter.h

@@ -30,8 +30,7 @@ namespace Oxide{
          * \param parent The parent object. Usually should be qApp
          */
         explicit EventFilter(QObject* parent = nullptr);
-    signals:
-        void suspend();
+
     protected:
         bool eventFilter(QObject* obj, QEvent* ev);
     };

shared/liboxide/liboxide.pro

@@ -137,5 +137,6 @@ RESOURCES += \
     oxide.qrc
 
 DISTFILES += \
+    Doxyfile \
     OxideMenu.qml \
     OxideWindow.qml

shared/liboxide/liboxide_global.h

@@ -1,8 +1,3 @@
-/*!
- * \addtogroup Oxide
- * @{
- * \file
- */
 #pragma once
 
 #include <QtCore/qglobal.h>
@@ -23,4 +18,3 @@
 #else
 # define ATTRIBUTE_NO_SANITIZE_ADDRESS
 #endif
-/*! @} */