docs: add API documentation for SystemTray and DBusMenu

Author: outfoxxed

docs

@@ -24,8 +24,11 @@ Q_NAMESPACE;
 QML_ELEMENT;
 
 enum Enum {
+	/// This menu item does not have a checkbox or a radiobutton associated with it.
 	None = 0,
+	/// This menu item should draw a checkbox.
 	CheckBox = 1,
+	/// This menu item should draw a radiobutton.
 	RadioButton = 2,
 };
 Q_ENUM_NS(Enum);
@@ -41,19 +44,64 @@ QDebug operator<<(QDebug debug, const ToggleButtonType::Enum& toggleType);
 class DBusMenu;
 class DBusMenuPngImage;
 
+///! Menu item shared by an external program.
+/// Menu item shared by an external program via the
+/// [DBusMenu specification](https://github.com/AyatanaIndicators/libdbusmenu/blob/master/libdbusmenu-glib/dbus-menu.xml).
 class DBusMenuItem: public QObject {
 	Q_OBJECT;
 	// clang-format off
+	/// Handle to the root of this menu.
 	Q_PROPERTY(DBusMenu* menuHandle READ menuHandle CONSTANT);
+	/// Text of the menu item, including hotkey markup.
 	Q_PROPERTY(QString label READ label NOTIFY labelChanged);
+	/// Text of the menu item without hotkey markup.
 	Q_PROPERTY(QString cleanLabel READ cleanLabel NOTIFY labelChanged);
+  /// If the menu item should be shown as enabled.
+	///
+	/// > [!INFO] Disabled menu items are often used as headers in addition
+	/// > to actual disabled entries.
 	Q_PROPERTY(bool enabled READ enabled NOTIFY enabledChanged);
+	/// Url of the menu item's icon or `""` if it doesn't have one.
+	///
+	/// This can be passed to [Image.source](https://doc.qt.io/qt-6/qml-qtquick-image.html#source-prop)
+	/// as shown below.
+	///
+	/// ```qml
+	/// Image {
+	///   source: menuItem.icon
+	///   // To get the best image quality, set the image source size to the same size
+	///   // as the rendered image.
+	///   sourceSize.width: width
+	///   sourceSize.height: height
+	/// }
+	/// ```
 	Q_PROPERTY(QString icon READ icon NOTIFY iconChanged);
+	/// If this menu item has an associated checkbox or radiobutton.
+	///
+	/// > [!INFO] It is the responsibility of the remote application to update the state of
+	/// > checkboxes and radiobuttons via [checkState](#prop.checkState).
 	Q_PROPERTY(ToggleButtonType::Enum toggleType READ toggleType NOTIFY toggleTypeChanged);
+	/// The check state of the checkbox or radiobutton if applicable, as a
+  /// [Qt.CheckState](https://doc.qt.io/qt-6/qt.html#CheckState-enum).
 	Q_PROPERTY(Qt::CheckState checkState READ checkState NOTIFY checkStateChanged);
+	/// If this menu item should be rendered as a separator between other items.
+	///
+	/// No other properties have a meaningful value when `isSeparator` is true.
 	Q_PROPERTY(bool isSeparator READ isSeparator NOTIFY separatorChanged);
+	/// If this menu item reveals a submenu containing more items.
+	///
+	/// Any submenu items must be requested by setting [showChildren](#prop.showChildren).
 	Q_PROPERTY(bool hasChildren READ hasChildren NOTIFY hasChildrenChanged);
+	/// If submenu entries of this item should be shown.
+	///
+	/// When true, children of this menu item will be exposed via [children](#prop.children).
+	/// Setting this property will additionally send the `opened` and `closed` events to the
+	/// process that provided the menu.
 	Q_PROPERTY(bool showChildren READ isShowingChildren WRITE setShowChildren NOTIFY showingChildrenChanged);
+	/// Children of this menu item. Only populated when [showChildren](#prop.showChildren) is true.
+	///
+	/// > [!INFO] Use [hasChildren](#prop.hasChildren) to check if this item should reveal a submenu
+	/// > instead of checking if `children` is empty.
 	Q_PROPERTY(QQmlListProperty<DBusMenuItem> children READ children NOTIFY childrenChanged);
 	// clang-format on
 	QML_NAMED_ELEMENT(DBusMenu);
@@ -62,7 +110,12 @@ class DBusMenuItem: public QObject {
 public:
 	explicit DBusMenuItem(qint32 id, DBusMenu* menu, DBusMenuItem* parentMenu);
 
+	/// Send a `clicked` event to the remote application for this menu item.
 	Q_INVOKABLE void click();
+
+	/// Send a `hovered` event to the remote application for this menu item.
+	///
+	/// Note: we are not aware of any programs that use this in any meaningful way.
 	Q_INVOKABLE void hover() const;
 
 	[[nodiscard]] DBusMenu* menuHandle() const;
@@ -122,6 +175,8 @@ class DBusMenuItem: public QObject {
 
 QDebug operator<<(QDebug debug, DBusMenuItem* item);
 
+///! Handle to a DBusMenu tree.
+/// Handle to a menu tree provided by a remote process.
 class DBusMenu: public QObject {
 	Q_OBJECT;
 	Q_PROPERTY(DBusMenuItem* menu READ menu CONSTANT);

src/dbus/dbusmenu/dbusmenu.hpp

@@ -0,0 +1,4 @@
+name = "Quickshell.DBusMenu"
+description = "Types related to DBusMenu (used in system tray)"
+headers = [ "dbusmenu.hpp" ]
+-----

src/dbus/dbusmenu/module.md

@@ -0,0 +1,4 @@
+name = "Quickshell.Service.SystemTray"
+description = "Types for implementing a system tray"
+headers = [ "qml.hpp" ]
+-----

src/services/status_notifier/module.md

@@ -13,11 +13,11 @@ Q_NAMESPACE;
 QML_ELEMENT;
 
 enum Enum {
-	// A passive item does not convey important information and can be considered idle. You may want to hide these.
+	/// A passive item does not convey important information and can be considered idle. You may want to hide these.
 	Passive = 0,
-	// An active item may have information more important than a passive one and you probably do not want to hide it.
+	/// An active item may have information more important than a passive one and you probably do not want to hide it.
 	Active = 1,
-	// An item that needs attention conveys very important information such as low battery.
+	/// An item that needs attention conveys very important information such as low battery.
 	NeedsAttention = 2,
 };
 Q_ENUM_NS(Enum);
@@ -29,12 +29,12 @@ Q_NAMESPACE;
 QML_ELEMENT;
 
 enum Enum {
-	// The fallback category for general applications or anything that does
-	// not fit into a different category.
+	/// The fallback category for general applications or anything that does
+	/// not fit into a different category.
 	ApplicationStatus = 0,
-	// System services such as IMEs or disk indexing.
+	/// System services such as IMEs or disk indexing.
 	SystemServices = 1,
-	// Hardware controls like battery indicators or volume control.
+	/// Hardware controls like battery indicators or volume control.
 	Hardware = 2,
 };
 Q_ENUM_NS(Enum);
@@ -47,33 +47,36 @@ Q_ENUM_NS(Enum);
 ///
 /// [kde/freedesktop spec]: https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/StatusNotifierItem/
 class SystemTrayItem: public QObject {
+	using DBusMenuItem = qs::dbus::dbusmenu::DBusMenuItem;
+
 	Q_OBJECT;
-	// A name unique to the application, such as its name.
+	/// A name unique to the application, such as its name.
 	Q_PROPERTY(QString id READ id NOTIFY idChanged);
-	// A name that describes the application
+	/// Text that describes the application.
 	Q_PROPERTY(QString title READ title NOTIFY titleChanged);
 	Q_PROPERTY(SystemTrayStatus::Enum status READ status NOTIFY statusChanged);
 	Q_PROPERTY(SystemTrayCategory::Enum category READ category NOTIFY categoryChanged);
-	// Icon source string, usable as an Image source.
+	/// Icon source string, usable as an Image source.
 	Q_PROPERTY(QString icon READ icon NOTIFY iconChanged);
 	Q_PROPERTY(QString tooltipTitle READ tooltipTitle NOTIFY tooltipTitleChanged);
 	Q_PROPERTY(QString tooltipDescription READ tooltipDescription NOTIFY tooltipDescriptionChanged);
-	Q_PROPERTY(qs::dbus::dbusmenu::DBusMenuItem* menu READ menu NOTIFY menuChanged);
-	// If this tray item only offers a menu and no activation action.
+	// The context menu provided by the application, generally displayed via a right click.
+	Q_PROPERTY(DBusMenuItem* menu READ menu NOTIFY menuChanged);
+	/// If this tray item only offers a menu and activation will do nothing.
 	Q_PROPERTY(bool onlyMenu READ onlyMenu NOTIFY onlyMenuChanged);
 	QML_ELEMENT;
 	QML_UNCREATABLE("SystemTrayItems can only be acquired from SystemTray");
 
 public:
 	explicit SystemTrayItem(qs::service::sni::StatusNotifierItem* item, QObject* parent = nullptr);
 
-	// Primary activation action, generally triggered via a left click.
+	/// Primary activation action, generally triggered via a left click.
 	Q_INVOKABLE void activate();
 
-	// Secondary activation action, generally triggered via a middle click.
+	/// Secondary activation action, generally triggered via a middle click.
 	Q_INVOKABLE void secondaryActivate();
 
-	// Scroll action, such as changing volume on a mixer.
+	/// Scroll action, such as changing volume on a mixer.
 	Q_INVOKABLE void scroll(qint32 delta, bool horizontal);
 
 	[[nodiscard]] QString id() const;
@@ -83,7 +86,7 @@ class SystemTrayItem: public QObject {
 	[[nodiscard]] QString icon() const;
 	[[nodiscard]] QString tooltipTitle() const;
 	[[nodiscard]] QString tooltipDescription() const;
-	[[nodiscard]] qs::dbus::dbusmenu::DBusMenuItem* menu() const;
+	[[nodiscard]] DBusMenuItem* menu() const;
 	[[nodiscard]] bool onlyMenu() const;
 
 signals:
@@ -107,8 +110,13 @@ private slots:
 	friend class SystemTray;
 };
 
+///! System tray
+/// Referencing the SystemTray singleton will make quickshell start tracking
+/// system tray contents, which are updated as the tray changes, and can be
+/// accessed via the `items` property.
 class SystemTray: public QObject {
 	Q_OBJECT;
+	/// List of all system tray icons.
 	Q_PROPERTY(QQmlListProperty<SystemTrayItem> items READ items NOTIFY itemsChanged);
 	QML_ELEMENT;
 	QML_SINGLETON;