From 36c072c08693e7abf8401698da65129ed57b9ba7 Mon Sep 17 00:00:00 2001
From: reuk <reuk@users.noreply.github.com>
Date: Wed, 13 Jan 2021 11:39:45 +0000
Subject: [PATCH] UMP:  Add missing docstrings

---
 .../ump/juce_UMPBytestreamInputHandler.h      | 14 ++++++++++
 .../midi_io/ump/juce_UMPConverters.h          | 26 +++++++++++++++++++
 .../midi_io/ump/juce_UMPFactory.h             |  7 +++++
 .../midi_io/ump/juce_UMPSysEx7.h              |  7 +++++
 .../midi_io/ump/juce_UMPU32InputHandler.h     | 14 ++++++++++
 .../midi_io/ump/juce_UMPUtils.h               |  9 +++++++
 6 files changed, 77 insertions(+)

diff --git a/modules/juce_audio_devices/midi_io/ump/juce_UMPBytestreamInputHandler.h b/modules/juce_audio_devices/midi_io/ump/juce_UMPBytestreamInputHandler.h
index 0ff560fef5..49ce664272 100644
--- a/modules/juce_audio_devices/midi_io/ump/juce_UMPBytestreamInputHandler.h
+++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPBytestreamInputHandler.h
@@ -45,6 +45,13 @@ struct BytestreamToBytestreamHandler : public BytestreamInputHandler
     BytestreamToBytestreamHandler (MidiInput& i, MidiInputCallback& c)
         : input (i), callback (c), concatenator (2048) {}
 
+    /**
+        Provides an `operator()` which can create an input handler for a given
+        MidiInput.
+
+        All handler classes should have a similar Factory to facilitate
+        creation of handlers in generic contexts.
+    */
     class Factory
     {
     public:
@@ -85,6 +92,13 @@ struct BytestreamToUMPHandler : public BytestreamInputHandler
     BytestreamToUMPHandler (PacketProtocol protocol, Receiver& c)
         : recipient (c), dispatcher (protocol, 2048) {}
 
+    /**
+        Provides an `operator()` which can create an input handler for a given
+        MidiInput.
+
+        All handler classes should have a similar Factory to facilitate
+        creation of handlers in generic contexts.
+    */
     class Factory
     {
     public:
diff --git a/modules/juce_audio_devices/midi_io/ump/juce_UMPConverters.h b/modules/juce_audio_devices/midi_io/ump/juce_UMPConverters.h
index 4e14ce38e6..d47927bd03 100644
--- a/modules/juce_audio_devices/midi_io/ump/juce_UMPConverters.h
+++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPConverters.h
@@ -24,6 +24,12 @@ namespace juce
 {
 namespace universal_midi_packets
 {
+    /**
+        Allows conversion from bytestream- or Universal MIDI Packet-formatted
+        messages to MIDI 1.0 messages in UMP format.
+
+        @tags{Audio}
+    */
     struct ToUMP1Converter
     {
         template <typename Fn>
@@ -39,6 +45,12 @@ namespace universal_midi_packets
         }
     };
 
+    /**
+        Allows conversion from bytestream- or Universal MIDI Packet-formatted
+        messages to MIDI 2.0 messages in UMP format.
+
+        @tags{Audio}
+    */
     struct ToUMP2Converter
     {
         template <typename Fn>
@@ -64,6 +76,14 @@ namespace universal_midi_packets
         Midi1ToMidi2DefaultTranslator translator;
     };
 
+    /**
+        Allows conversion from bytestream- or Universal MIDI Packet-formatted
+        messages to UMP format.
+
+        The packet protocol can be selected using the constructor parameter.
+
+        @tags{Audio}
+    */
     class GenericUMPConverter
     {
     public:
@@ -111,6 +131,12 @@ namespace universal_midi_packets
         const PacketProtocol mode{};
     };
 
+    /**
+        Allows conversion from bytestream- or Universal MIDI Packet-formatted
+        messages to bytestream format.
+
+        @tags{Audio}
+    */
     struct ToBytestreamConverter
     {
         explicit ToBytestreamConverter (int storageSize)
diff --git a/modules/juce_audio_devices/midi_io/ump/juce_UMPFactory.h b/modules/juce_audio_devices/midi_io/ump/juce_UMPFactory.h
index 57c36b8ddf..acfcc6c8bc 100644
--- a/modules/juce_audio_devices/midi_io/ump/juce_UMPFactory.h
+++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPFactory.h
@@ -25,8 +25,15 @@ namespace juce
 namespace universal_midi_packets
 {
 
+/**
+    This struct holds functions that can be used to create different kinds
+    of Universal MIDI Packet.
+
+    @tags{Audio}
+*/
 struct Factory
 {
+    /** @internal */
     struct Detail
     {
         static PacketX1 makeSystem()   { return PacketX1{}.withMessageType (1); }
diff --git a/modules/juce_audio_devices/midi_io/ump/juce_UMPSysEx7.h b/modules/juce_audio_devices/midi_io/ump/juce_UMPSysEx7.h
index cfd2bd0f22..f5f898a7a1 100644
--- a/modules/juce_audio_devices/midi_io/ump/juce_UMPSysEx7.h
+++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPSysEx7.h
@@ -25,6 +25,12 @@ namespace juce
 namespace universal_midi_packets
 {
 
+/**
+    This struct acts as a single-file namespace for Univeral MIDI Packet
+    functionality related to 7-bit SysEx.
+
+    @tags{Audio}
+*/
 struct SysEx7
 {
     /** Returns the number of 64-bit packets required to hold a series of
@@ -52,6 +58,7 @@ struct SysEx7
         end          = 3
     };
 
+    /** Holds the bytes from a single SysEx-7 packet. */
     struct PacketBytes
     {
         std::array<uint8_t, 6> data;
diff --git a/modules/juce_audio_devices/midi_io/ump/juce_UMPU32InputHandler.h b/modules/juce_audio_devices/midi_io/ump/juce_UMPU32InputHandler.h
index a9cd7880a1..b5471aa80e 100644
--- a/modules/juce_audio_devices/midi_io/ump/juce_UMPU32InputHandler.h
+++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPU32InputHandler.h
@@ -46,6 +46,13 @@ struct U32ToBytestreamHandler : public U32InputHandler
     U32ToBytestreamHandler (MidiInput& i, MidiInputCallback& c)
         : input (i), callback (c), dispatcher (2048) {}
 
+    /**
+        Provides an `operator()` which can create an input handler for a given
+        MidiInput.
+
+        All handler classes should have a similar Factory to facilitate
+        creation of handlers in generic contexts.
+    */
     class Factory
     {
     public:
@@ -89,6 +96,13 @@ struct U32ToUMPHandler : public U32InputHandler
     U32ToUMPHandler (PacketProtocol protocol, Receiver& c)
         : recipient (c), converter (protocol) {}
 
+    /**
+        Provides an `operator()` which can create an input handler for a given
+        MidiInput.
+
+        All handler classes should have a similar Factory to facilitate
+        creation of handlers in generic contexts.
+    */
     class Factory
     {
     public:
diff --git a/modules/juce_audio_devices/midi_io/ump/juce_UMPUtils.h b/modules/juce_audio_devices/midi_io/ump/juce_UMPUtils.h
index 23742c3b1a..9bac9e4b16 100644
--- a/modules/juce_audio_devices/midi_io/ump/juce_UMPUtils.h
+++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPUtils.h
@@ -46,6 +46,9 @@ struct Utils
     */
     static uint32_t getNumWordsForMessageType (uint32_t);
 
+    /**
+        Helper functions for setting/getting 4-bit ranges inside a 32-bit word.
+    */
     template <size_t Index>
     struct U4
     {
@@ -62,6 +65,9 @@ struct Utils
         }
     };
 
+    /**
+        Helper functions for setting/getting 8-bit ranges inside a 32-bit word.
+    */
     template <size_t Index>
     struct U8
     {
@@ -78,6 +84,9 @@ struct Utils
         }
     };
 
+    /**
+        Helper functions for setting/getting 16-bit ranges inside a 32-bit word.
+    */
     template <size_t Index>
     struct U16
     {