Improve the port available_group and type documentation

4 files changed, 80 insertions, 8 deletions

diff --git a/PROTOCOL b/PROTOCOL
index 6d3a3c7c0..0b18edf03 100644
--- a/PROTOCOL
+++ b/PROTOCOL
@@ -429,7 +429,11 @@ Added two values to the pa_encoding_t enum:
 
 ## v34, implemented by >= 14.0
 
-Added available_group and type fields to the device port info.
+New fields in the port introspection data (duplicated for all port types:
+sink, source and card ports):
+
+    string available_group
+    uint32 type
 
 #### If you just changed the protocol, read this
 ## module-tunnel depends on the sink/source/sink-input/source-input protocol
diff --git a/src/modules/alsa/mixer/paths/analog-output.conf.common b/src/modules/alsa/mixer/paths/analog-output.conf.common
index 7bf346346..31d4b447b 100644
--- a/src/modules/alsa/mixer/paths/analog-output.conf.common
+++ b/src/modules/alsa/mixer/paths/analog-output.conf.common
@@ -53,6 +53,8 @@
 
 
 ; [General]
+; type = ...                             # The device type. It's highly recommended to set a type for every path.
+;                                        # See parse_type() in alsa-mixer.c for supported values.
 ; priority = ...                         # Priority for this path
 ; description-key = ...                  # The path description is looked up from a table in path_verify() in
 ;                                        # src/modules/alsa/alsa-mixer.c. By default the path name (i.e. the file name
diff --git a/src/pulse/def.h b/src/pulse/def.h
index 2e5a5ec37..4097bd89c 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -1070,7 +1070,9 @@ typedef enum pa_port_available {
 /** \endcond */
 #endif
 
-/** Port type. \since 14.0 */
+/** Port type. New types can be added in the future, so applications should
+ * gracefully handle situations where a type identifier doesn't match any item
+ * in this enumeration. \since 14.0 */
 typedef enum pa_device_port_type {
     PA_DEVICE_PORT_TYPE_UNKNOWN = 0,
     PA_DEVICE_PORT_TYPE_AUX = 1,
diff --git a/src/pulse/introspect.h b/src/pulse/introspect.h
index 89685b501..657510747 100644
--- a/src/pulse/introspect.h
+++ b/src/pulse/introspect.h
@@ -229,8 +229,31 @@ typedef struct pa_sink_port_info {
     const char *description;            /**< Description of this port */
     uint32_t priority;                  /**< The higher this value is, the more useful this port is as a default. */
     int available;                      /**< A flags (see #pa_port_available), indicating availability status of this port. \since 2.0 */
-    const char *available_group;        /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
-    uint32_t type;			/**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
+    const char *available_group;        /**< An indentifier for the group of ports that share their availability status with
+                                         * each other. This is meant especially for handling cases where one 3.5 mm connector
+                                         * is used for headphones, headsets and microphones, and the hardware can only tell
+                                         * that something was plugged in but not what exactly. In this situation the ports for
+                                         * all those devices share their availability status, and PulseAudio can't tell which
+                                         * one is actually plugged in, and some application may ask the user what was plugged
+                                         * in. Such applications should get a list of all card ports and compare their
+                                         * `available_group` fields. Ports that have the same group are those that need
+                                         * input from the user to determine which device was plugged in. The application should
+                                         * then activate the user-chosen port.
+                                         *
+                                         * May be NULL, in which case the port is not part of any availability group (which is
+                                         * the same as having a group with only one member).
+                                         *
+                                         * The group identifier must be treated as an opaque identifier. The string may look
+                                         * like an ALSA control name, but applications must not assume any such relationship.
+                                         * The group naming scheme can change without a warning.
+                                         *
+                                         * Since one group can include both input and output ports, the grouping should be done
+                                         * using pa_card_port_info instead of pa_sink_port_info, but this field is duplicated
+                                         * also in pa_sink_port_info (and pa_source_port_info) in case someone finds that
+                                         * convenient.
+                                         *
+                                         * \since 14.0 */
+    uint32_t type;			/**< Port type, see #pa_device_port_type. \since 14.0 */
 } pa_sink_port_info;
 
 /** Stores information about sinks. Please note that this structure
@@ -311,8 +334,31 @@ typedef struct pa_source_port_info {
     const char *description;            /**< Description of this port */
     uint32_t priority;                  /**< The higher this value is, the more useful this port is as a default. */
     int available;                      /**< A flags (see #pa_port_available), indicating availability status of this port. \since 2.0 */
-    const char *available_group;        /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
-    uint32_t type;			/**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
+    const char *available_group;        /**< An indentifier for the group of ports that share their availability status with
+                                         * each other. This is meant especially for handling cases where one 3.5 mm connector
+                                         * is used for headphones, headsets and microphones, and the hardware can only tell
+                                         * that something was plugged in but not what exactly. In this situation the ports for
+                                         * all those devices share their availability status, and PulseAudio can't tell which
+                                         * one is actually plugged in, and some application may ask the user what was plugged
+                                         * in. Such applications should get a list of all card ports and compare their
+                                         * `available_group` fields. Ports that have the same group are those that need
+                                         * input from the user to determine which device was plugged in. The application should
+                                         * then activate the user-chosen port.
+                                         *
+                                         * May be NULL, in which case the port is not part of any availability group (which is
+                                         * the same as having a group with only one member).
+                                         *
+                                         * The group identifier must be treated as an opaque identifier. The string may look
+                                         * like an ALSA control name, but applications must not assume any such relationship.
+                                         * The group naming scheme can change without a warning.
+                                         *
+                                         * Since one group can include both input and output ports, the grouping should be done
+                                         * using pa_card_port_info instead of pa_source_port_info, but this field is duplicated
+                                         * also in pa_source_port_info (and pa_sink_port_info) in case someone finds that
+                                         * convenient.
+                                         *
+                                         * \since 14.0 */
+    uint32_t type;		        /**< Port type, see #pa_device_port_type. \since 14.0 */
 } pa_source_port_info;
 
 /** Stores information about sources. Please note that this structure
@@ -513,8 +559,26 @@ typedef struct pa_card_port_info {
     pa_proplist *proplist;              /**< Property list */
     int64_t latency_offset;             /**< Latency offset of the port that gets added to the sink/source latency when the port is active. \since 3.0 */
     pa_card_profile_info2** profiles2;  /**< Array of pointers to available profiles, or NULL. Array is terminated by an entry set to NULL. \since 5.0 */
-    const char *available_group;        /**< A string indentifier which determine the group of devices handling the available state simultaneously. \since 14.0 */
-    uint32_t type;			/**< Port device type (PA_PORT_DEVICE_TYPE). \since 14.0 */
+    const char *available_group;        /**< An indentifier for the group of ports that share their availability status with
+                                         * each other. This is meant especially for handling cases where one 3.5 mm connector
+                                         * is used for headphones, headsets and microphones, and the hardware can only tell
+                                         * that something was plugged in but not what exactly. In this situation the ports for
+                                         * all those devices share their availability status, and PulseAudio can't tell which
+                                         * one is actually plugged in, and some application may ask the user what was plugged
+                                         * in. Such applications should get a list of all card ports and compare their
+                                         * `available_group` fields. Ports that have the same group are those that need
+                                         * input from the user to determine which device was plugged in. The application should
+                                         * then activate the user-chosen port.
+                                         *
+                                         * May be NULL, in which case the port is not part of any availability group (which is
+                                         * the same as having a group with only one member).
+                                         *
+                                         * The group identifier must be treated as an opaque identifier. The string may look
+                                         * like an ALSA control name, but applications must not assume any such relationship.
+                                         * The group naming scheme can change without a warning.
+                                         *
+                                         * \since 14.0 */
+    uint32_t type;			/**< Port type, see #pa_device_port_type. \since 14.0 */
 } pa_card_port_info;
 
 /** Stores information about cards. Please note that this structure