service/pipewire: improve documentation

src/services/pipewire/qml.hpp

@@ -52,11 +52,31 @@ private:
 class Pipewire: public QObject {
 	Q_OBJECT;
 	// clang-format off
-	/// All pipewire nodes.
+	/// All nodes present in pipewire.
+	///
+	/// This list contains every node on the system.
+	/// To find a useful subset, filtering with the following properties may be helpful:
+	/// - @@PwNode.isStream - if the node is an application or hardware device.
+	/// - @@PwNode.isSink - if the node is a sink or source.
+	/// - @@PwNode.audio - if non null the node is an audio node.
 	Q_PROPERTY(ObjectModel<PwNodeIface>* nodes READ nodes CONSTANT);
-	/// All pipewire links.
+	/// All links present in pipewire.
+	///
+	/// Links connect pipewire nodes to each other, and can be used to determine
+	/// their relationship.
+	///
+	/// If you already have a node you want to check for connections to,
+	/// use @@PwNodeLinkTracker instead of filtering this list.
+	///
+	/// > [!INFO] Multiple links may exist between the same nodes. See @@linkGroups
+	/// > for a deduplicated list containing only one entry per link between nodes.
 	Q_PROPERTY(ObjectModel<PwLinkIface>* links READ links CONSTANT);
-	/// All pipewire link groups.
+	/// All link groups present in pipewire.
+	///
+	/// The same as @@links but deduplicated.
+	///
+	/// If you already have a node you want to check for connections to,
+	/// use @@PwNodeLinkTracker instead of filtering this list.
 	Q_PROPERTY(ObjectModel<PwLinkGroupIface>* linkGroups READ linkGroups CONSTANT);
 	/// The default audio sink (output) or `null`.
 	///
@@ -231,7 +251,7 @@ class PwNodeIface: public PwObjectIface {
 	Q_OBJECT;
 	/// The pipewire object id of the node.
 	///
-	/// Mainly useful for debugging. you can inspect the node directly
+	/// Mainly useful for debugging. You can inspect the node directly
 	/// with `pw-cli i <id>`.
 	Q_PROPERTY(quint32 id READ id CONSTANT);
 	/// The node's name, corrosponding to the object's `node.name` property.
@@ -247,7 +267,8 @@ class PwNodeIface: public PwObjectIface {
 	/// If `true`, then the node accepts audio input from other nodes,
 	/// if `false` the node outputs audio to other nodes.
 	Q_PROPERTY(bool isSink READ isSink CONSTANT);
-	/// If `true` then the node is likely to be a program, if false it is liekly to be hardware.
+	/// If `true` then the node is likely to be a program, if `false` it is likely to be
+	/// a hardware device.
 	Q_PROPERTY(bool isStream READ isStream CONSTANT);
 	/// The property set present on the node, as an object containing key-value pairs.
 	/// You can inspect this directly with `pw-cli i <id>`.
@@ -263,6 +284,9 @@ class PwNodeIface: public PwObjectIface {
 	/// > [!WARNING] This property is invalid unless the node is [bound](../pwobjecttracker).
 	Q_PROPERTY(QVariantMap properties READ properties NOTIFY propertiesChanged);
 	/// Extra information present only if the node sends or receives audio.
+	///
+	/// The presence or absence of this property can be used to determine if a node
+	/// manages audio, regardless of if it is bound. If non null, the node is an audio node.
 	Q_PROPERTY(PwNodeAudioIface* audio READ audio CONSTANT);
 	QML_NAMED_ELEMENT(PwNode);
 	QML_UNCREATABLE("PwNodes cannot be created directly");
@@ -370,11 +394,19 @@ private:
 };
 
 ///! Binds pipewire objects.
-/// If the object list of at least one PwObjectTracker contains a given pipewire object,
+/// PwObjectTracker binds every node given in its @@objects list.
-/// it will become *bound* and you will be able to interact with bound-only properties.
+///
+/// #### Object Binding
+/// By default, pipewire objects are unbound. Unbound objects only have a subset of
+/// information available for use or modification. **Binding an object makes all of its
+/// properties available for use or modification if applicable.**
+///
+/// Properties that require their object be bound to use are clearly marked. You do not
+/// need to bind the object unless mentioned in the description of the property you
+/// want to use.
 class PwObjectTracker: public QObject {
 	Q_OBJECT;
-	/// The list of objects to bind.
+	/// The list of objects to bind. May contain nulls.
 	Q_PROPERTY(QList<QObject*> objects READ objects WRITE setObjects NOTIFY objectsChanged);
 	QML_ELEMENT;