From f8df0235979c14a47822b68622c0872fa923685e Mon Sep 17 00:00:00 2001
From: Takashi Iwai <tiwai@suse.de>
Date: Wed, 26 Jun 2024 11:23:34 +0200
Subject: [PATCH] ump: Add descriptions for UMP RawMidi interface

Also update doxygen config accordingly.

Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
 doc/doxygen.cfg.in |  2 ++
 include/ump.h      |  8 ++++++++
 src/rawmidi/ump.c  | 23 +++++++++++++++++++++++
 3 files changed, 33 insertions(+)

diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in
index 8bf29b21..bcc3a33e 100644
--- a/doc/doxygen.cfg.in
+++ b/doc/doxygen.cfg.in
@@ -17,6 +17,8 @@ INPUT            = @top_srcdir@/doc/index.doxygen \
 		   @top_srcdir@/include/control.h \
 		   @top_srcdir@/include/pcm.h \
 		   @top_srcdir@/include/rawmidi.h \
+		   @top_srcdir@/include/ump.h \
+		   @top_srcdir@/include/ump_msg.h \
 		   @top_srcdir@/include/timer.h \
 		   @top_srcdir@/include/hwdep.h \
 		   @top_srcdir@/include/seq.h \
diff --git a/include/ump.h b/include/ump.h
index 01363a32..1043d237 100644
--- a/include/ump.h
+++ b/include/ump.h
@@ -13,6 +13,12 @@
 extern "C" {
 #endif
 
+/**
+ *  \defgroup RawMidi RawMidi Interface
+ *  The RawMidi Interface. See \ref rawmidi page for more details.
+ *  \{
+ */
+
 /** UMP (Endpoint) RawMIDI device */
 typedef struct _snd_ump snd_ump_t;
 /** UMP Endpoint information container */
@@ -168,6 +174,8 @@ void snd_ump_block_info_set_sysex8_streams(snd_ump_block_info_t *info, unsigned
 void snd_ump_block_info_set_ui_hint(snd_ump_block_info_t *info, unsigned int hint);
 void snd_ump_block_info_set_name(snd_ump_block_info_t *info, const char *name);
 
+/** \} */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/src/rawmidi/ump.c b/src/rawmidi/ump.c
index 88c9a26b..fddb60c2 100644
--- a/src/rawmidi/ump.c
+++ b/src/rawmidi/ump.c
@@ -7,6 +7,29 @@
 #include "rawmidi_local.h"
 #include "ump_local.h"
 
+/*! \page rawmidi RawMidi interface
+
+\section rawmidi_ump UMP RawMidi Interface
+
+MIDI 2.0 devices have a different type of interface, communicating with
+UMP (Universal MIDI Packet).  For those devices, ALSA-library provides
+API functions for accessing the raw UMP packet directly via the existing
+RawMidi interface.
+
+#snd_ump_open() is the API function for opening a UMP RawMidi interface.
+It works just like #snd_rawmidi_open() but for UMP devices.  Similarly,
+#snd_ump_close() is for closing, and there are other equivalent API functions
+corresponding to the RawMidi ones.
+
+The new stuff for UMP is UMP Endpoint and UMP Function Blocks.  The information
+from Endpoint and Function Blocks can be obtained via #snd_ump_endpoint_info()
+and #snd_ump_block_info() API functions.
+
+The objects #snd_ump_endpoint_info_t and #snd_ump_block_info_t are used for
+creating a virtual UMP Endpoint and Function Blocks via ALSA sequencer, too.
+
+*/
+
 static int get_rawmidi_flags(snd_ump_t *ump)
 {
 	snd_rawmidi_info_t info;