From d5099ecf4d9cbd3cc638deda3cf53867617e5c13 Mon Sep 17 00:00:00 2001 From: reuk Date: Wed, 8 Dec 2021 14:13:44 +0000 Subject: [PATCH] Documentation: Add doxygen guards to UMP namespace --- modules/juce_audio_basics/midi/ump/juce_UMP.h | 4 +++ .../midi/ump/juce_UMPConversion.h | 32 +++++++++++-------- .../midi/ump/juce_UMPConverters.h | 12 ++++--- .../midi/ump/juce_UMPDispatcher.h | 24 ++++++++------ .../midi/ump/juce_UMPFactory.h | 8 +++-- .../midi/ump/juce_UMPIterator.h | 22 +++++++------ .../ump/juce_UMPMidi1ToBytestreamTranslator.h | 14 +++++--- .../juce_UMPMidi1ToMidi2DefaultTranslator.h | 8 +++-- .../midi/ump/juce_UMPProtocols.h | 8 +++-- .../midi/ump/juce_UMPReceiver.h | 8 +++-- .../midi/ump/juce_UMPSysEx7.h | 22 +++++++------ .../midi/ump/juce_UMPUtils.h | 16 ++++++---- .../juce_audio_basics/midi/ump/juce_UMPView.h | 24 ++++++++------ .../midi/ump/juce_UMPacket.h | 6 +++- .../midi/ump/juce_UMPackets.h | 20 +++++++----- .../ump/juce_UMPBytestreamInputHandler.h | 14 +++++--- .../midi_io/ump/juce_UMPU32InputHandler.h | 14 +++++--- 17 files changed, 162 insertions(+), 94 deletions(-) diff --git a/modules/juce_audio_basics/midi/ump/juce_UMP.h b/modules/juce_audio_basics/midi/ump/juce_UMP.h index 1d31028002..e6ce3aff51 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMP.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMP.h @@ -37,7 +37,11 @@ #include "juce_UMPDispatcher.h" #include "juce_UMPReceiver.h" +#ifndef DOXYGEN + namespace juce { namespace ump = universal_midi_packets; } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPConversion.h b/modules/juce_audio_basics/midi/ump/juce_UMPConversion.h index dd7c36f96b..86ae339102 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPConversion.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPConversion.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Functions to assist conversion of UMP messages to/from other formats, especially older 'bytestream' formatted MidiMessages. @@ -33,7 +35,7 @@ namespace universal_midi_packets */ struct Conversion { - /* Converts from a MIDI 1 bytestream to MIDI 1 on Universal MIDI Packets. + /** Converts from a MIDI 1 bytestream to MIDI 1 on Universal MIDI Packets. `callback` is a function which accepts a single View argument. */ @@ -97,7 +99,7 @@ struct Conversion } } - /* Converts a MidiMessage to one or more messages in UMP format, using + /** Converts a MidiMessage to one or more messages in UMP format, using the MIDI 1.0 Protocol. `packets` is an out-param to allow the caller to control @@ -111,7 +113,7 @@ struct Conversion toMidi1 (m, [&] (const View& view) { packets.add (view); }); } - /* Widens a 7-bit MIDI 1.0 value to a 8-bit MIDI 2.0 value. */ + /** Widens a 7-bit MIDI 1.0 value to a 8-bit MIDI 2.0 value. */ static uint8_t scaleTo8 (uint8_t word7Bit) { const auto shifted = (uint8_t) (word7Bit << 0x1); @@ -120,7 +122,7 @@ struct Conversion return (uint8_t) (shifted | ((repeat >> 5) & mask)); } - /* Widens a 7-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */ + /** Widens a 7-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */ static uint16_t scaleTo16 (uint8_t word7Bit) { const auto shifted = (uint16_t) (word7Bit << 0x9); @@ -129,7 +131,7 @@ struct Conversion return (uint16_t) (shifted | (((repeat << 3) | (repeat >> 3)) & mask)); } - /* Widens a 14-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */ + /** Widens a 14-bit MIDI 1.0 value to a 16-bit MIDI 2.0 value. */ static uint16_t scaleTo16 (uint16_t word14Bit) { const auto shifted = (uint16_t) (word14Bit << 0x2); @@ -138,7 +140,7 @@ struct Conversion return (uint16_t) (shifted | ((repeat >> 11) & mask)); } - /* Widens a 7-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */ + /** Widens a 7-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */ static uint32_t scaleTo32 (uint8_t word7Bit) { const auto shifted = (uint32_t) (word7Bit << 0x19); @@ -151,7 +153,7 @@ struct Conversion | (repeat >> 5)) & mask)); } - /* Widens a 14-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */ + /** Widens a 14-bit MIDI 1.0 value to a 32-bit MIDI 2.0 value. */ static uint32_t scaleTo32 (uint16_t word14Bit) { const auto shifted = (uint32_t) (word14Bit << 0x12); @@ -160,22 +162,22 @@ struct Conversion return (uint32_t) (shifted | (((repeat << 5) | (repeat >> 8)) & mask)); } - /* Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */ + /** Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */ static uint8_t scaleTo7 (uint8_t word8Bit) { return (uint8_t) (word8Bit >> 1); } - /* Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */ + /** Narrows a 16-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */ static uint8_t scaleTo7 (uint16_t word16Bit) { return (uint8_t) (word16Bit >> 9); } - /* Narrows a 32-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */ + /** Narrows a 32-bit MIDI 2.0 value to a 7-bit MIDI 1.0 value. */ static uint8_t scaleTo7 (uint32_t word32Bit) { return (uint8_t) (word32Bit >> 25); } - /* Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */ + /** Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */ static uint16_t scaleTo14 (uint16_t word16Bit) { return (uint16_t) (word16Bit >> 2); } - /* Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */ + /** Narrows a 32-bit MIDI 2.0 value to a 14-bit MIDI 1.0 value. */ static uint16_t scaleTo14 (uint32_t word32Bit) { return (uint16_t) (word32Bit >> 18); } - /* Converts UMP messages which may include MIDI 2.0 channel voice messages into + /** Converts UMP messages which may include MIDI 2.0 channel voice messages into equivalent MIDI 1.0 messages (still in UMP format). `callback` is a function that accepts a single View argument and will be @@ -324,3 +326,5 @@ struct Conversion } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPConverters.h b/modules/juce_audio_basics/midi/ump/juce_UMPConverters.h index 9c8d803dfc..a0bbee9160 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPConverters.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPConverters.h @@ -20,11 +20,13 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { - /* + /** Allows conversion from bytestream- or Universal MIDI Packet-formatted messages to MIDI 1.0 messages in UMP format. @@ -45,7 +47,7 @@ namespace universal_midi_packets } }; - /* + /** Allows conversion from bytestream- or Universal MIDI Packet-formatted messages to MIDI 2.0 messages in UMP format. @@ -76,7 +78,7 @@ namespace universal_midi_packets Midi1ToMidi2DefaultTranslator translator; }; - /* + /** Allows conversion from bytestream- or Universal MIDI Packet-formatted messages to UMP format. @@ -131,7 +133,7 @@ namespace universal_midi_packets const PacketProtocol mode{}; }; - /* + /** Allows conversion from bytestream- or Universal MIDI Packet-formatted messages to bytestream format. @@ -163,3 +165,5 @@ namespace universal_midi_packets }; } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPDispatcher.h b/modules/juce_audio_basics/midi/ump/juce_UMPDispatcher.h index ec296a9806..ab1277cc4b 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPDispatcher.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPDispatcher.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Parses a raw stream of uint32_t, and calls a user-provided callback every time a full Universal MIDI Packet is encountered. @@ -34,10 +36,10 @@ namespace universal_midi_packets class Dispatcher { public: - /* Clears the dispatcher. */ + /** Clears the dispatcher. */ void reset() { currentPacketLen = 0; } - /* Calls `callback` with a View of each packet encountered in the range delimited + /** Calls `callback` with a View of each packet encountered in the range delimited by `begin` and `end`. If the range ends part-way through a packet, the next call to `dispatch` will @@ -67,7 +69,7 @@ private: }; //============================================================================== -/* +/** Parses a stream of bytes representing a sequence of bytestream-encoded MIDI 1.0 messages, converting the messages to UMP format and passing the packets to a user-provided callback as they become ready. @@ -77,7 +79,7 @@ private: class BytestreamToUMPDispatcher { public: - /* Initialises the dispatcher. + /** Initialises the dispatcher. Channel messages will be converted to the requested protocol format `pp`. `storageSize` bytes will be allocated to store incomplete messages. @@ -93,7 +95,7 @@ public: converter.reset(); } - /* Calls `callback` with a View of each converted packet as it becomes ready. + /** Calls `callback` with a View of each converted packet as it becomes ready. @param begin the first byte in a range of bytes representing bytestream-encoded MIDI messages. @param end one-past the last byte in a range of bytes representing bytestream-encoded MIDI messages. @@ -145,7 +147,7 @@ private: }; //============================================================================== -/* +/** Parses a stream of 32-bit words representing a sequence of UMP-encoded MIDI messages, converting the messages to MIDI 1.0 bytestream format and passing them to a user-provided callback as they become ready. @@ -155,21 +157,21 @@ private: class ToBytestreamDispatcher { public: - /* Initialises the dispatcher. + /** Initialises the dispatcher. `storageSize` bytes will be allocated to store incomplete messages. */ explicit ToBytestreamDispatcher (int storageSize) : converter (storageSize) {} - /* Clears the dispatcher. */ + /** Clears the dispatcher. */ void reset() { dispatcher.reset(); converter.reset(); } - /* Calls `callback` with converted bytestream-formatted MidiMessage whenever + /** Calls `callback` with converted bytestream-formatted MidiMessage whenever a new message becomes available. @param begin the first word in a stream of words representing UMP-encoded MIDI packets. @@ -196,3 +198,5 @@ private: } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPFactory.h b/modules/juce_audio_basics/midi/ump/juce_UMPFactory.h index b89d08e969..f1d937d793 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPFactory.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPFactory.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** This struct holds functions that can be used to create different kinds of Universal MIDI Packet. @@ -33,7 +35,7 @@ namespace universal_midi_packets */ struct Factory { - /* @internal */ + /** @internal */ struct Detail { static PacketX1 makeSystem() { return PacketX1{}.withMessageType (1); } @@ -532,3 +534,5 @@ struct Factory } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPIterator.h b/modules/juce_audio_basics/midi/ump/juce_UMPIterator.h index c562dfc2ce..1800388a96 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPIterator.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPIterator.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Enables iteration over a collection of Universal MIDI Packets stored as a contiguous range of 32-bit words. @@ -37,10 +39,10 @@ namespace universal_midi_packets class Iterator { public: - /* Creates an invalid (singular) iterator. */ + /** Creates an invalid (singular) iterator. */ Iterator() noexcept = default; - /* Creates an iterator pointing at `ptr`. */ + /** Creates an iterator pointing at `ptr`. */ explicit Iterator (const uint32_t* ptr, size_t bytes) noexcept : view (ptr) #if JUCE_DEBUG @@ -56,7 +58,7 @@ public: using pointer = const View*; using iterator_category = std::forward_iterator_tag; - /* Moves this iterator to the next packet in the range. */ + /** Moves this iterator to the next packet in the range. */ Iterator& operator++() noexcept { const auto increment = view.size(); @@ -73,7 +75,7 @@ public: return *this; } - /* Moves this iterator to the next packet in the range, + /** Moves this iterator to the next packet in the range, returning the value of the iterator before it was incremented. */ @@ -84,7 +86,7 @@ public: return copy; } - /* Returns true if this iterator points to the same address + /** Returns true if this iterator points to the same address as another iterator. */ bool operator== (const Iterator& other) const noexcept @@ -92,7 +94,7 @@ public: return view == other.view; } - /* Returns false if this iterator points to the same address + /** Returns false if this iterator points to the same address as another iterator. */ bool operator!= (const Iterator& other) const noexcept @@ -100,14 +102,14 @@ public: return ! operator== (other); } - /* Returns a reference to a View of the packet currently + /** Returns a reference to a View of the packet currently pointed-to by this iterator. The View can be queried for its size and content. */ reference operator*() noexcept { return view; } - /* Returns a pointer to a View of the packet currently + /** Returns a pointer to a View of the packet currently pointed-to by this iterator. The View can be queried for its size and content. @@ -124,3 +126,5 @@ private: } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToBytestreamTranslator.h b/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToBytestreamTranslator.h index 0bde9a276c..514cd0170a 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToBytestreamTranslator.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToBytestreamTranslator.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Parses a raw stream of uint32_t holding a series of Universal MIDI Packets using the MIDI 1.0 Protocol, converting to plain (non-UMP) MidiMessages. @@ -34,7 +36,7 @@ namespace universal_midi_packets class Midi1ToBytestreamTranslator { public: - /* Ensures that there is room in the internal buffer for a sysex message of at least + /** Ensures that there is room in the internal buffer for a sysex message of at least `initialBufferSize` bytes. */ explicit Midi1ToBytestreamTranslator (int initialBufferSize) @@ -42,14 +44,14 @@ public: pendingSysExData.reserve (size_t (initialBufferSize)); } - /* Clears the concatenator. */ + /** Clears the concatenator. */ void reset() { pendingSysExData.clear(); pendingSysExTime = 0.0; } - /* Converts a Universal MIDI Packet using the MIDI 1.0 Protocol to + /** Converts a Universal MIDI Packet using the MIDI 1.0 Protocol to an equivalent MidiMessage. Accumulates SysEx packets into a single MidiMessage, as appropriate. @@ -91,7 +93,7 @@ public: } } - /* Converts from a Universal MIDI Packet to MIDI 1 bytestream format. + /** Converts from a Universal MIDI Packet to MIDI 1 bytestream format. This is only capable of converting a single Universal MIDI Packet to an equivalent bytestream MIDI message. This function cannot understand @@ -211,3 +213,5 @@ private: } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToMidi2DefaultTranslator.h b/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToMidi2DefaultTranslator.h index 35f750b451..77e5076650 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToMidi2DefaultTranslator.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPMidi1ToMidi2DefaultTranslator.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Translates a series of MIDI 1 Universal MIDI Packets to corresponding MIDI 2 packets. @@ -36,7 +38,7 @@ class Midi1ToMidi2DefaultTranslator public: Midi1ToMidi2DefaultTranslator() = default; - /* Converts MIDI 1 Universal MIDI Packets to corresponding MIDI 2 packets, + /** Converts MIDI 1 Universal MIDI Packets to corresponding MIDI 2 packets, calling `callback` with each converted packet. In some cases (such as RPN/NRPN messages) multiple MIDI 1 packets will @@ -185,3 +187,5 @@ private: } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPProtocols.h b/modules/juce_audio_basics/midi/ump/juce_UMPProtocols.h index b03594c94b..2e6df20851 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPProtocols.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPProtocols.h @@ -20,19 +20,21 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* The kinds of MIDI protocol that can be formatted into Universal MIDI Packets. */ +/** The kinds of MIDI protocol that can be formatted into Universal MIDI Packets. */ enum class PacketProtocol { MIDI_1_0, MIDI_2_0, }; -/* All kinds of MIDI protocol understood by JUCE. */ +/** All kinds of MIDI protocol understood by JUCE. */ enum class MidiProtocol { bytestream, @@ -42,3 +44,5 @@ enum class MidiProtocol } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPReceiver.h b/modules/juce_audio_basics/midi/ump/juce_UMPReceiver.h index b8dbbc4d46..467857349e 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPReceiver.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPReceiver.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** A base class for classes which receive Universal MIDI Packets from an input. @tags{Audio} @@ -34,9 +36,11 @@ struct Receiver { virtual ~Receiver() noexcept = default; - /* This will be called each time a new packet is ready for processing. */ + /** This will be called each time a new packet is ready for processing. */ virtual void packetReceived (const View& packet, double time) = 0; }; } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPSysEx7.h b/modules/juce_audio_basics/midi/ump/juce_UMPSysEx7.h index 4f97ec8de5..2a264bbdba 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPSysEx7.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPSysEx7.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** This struct acts as a single-file namespace for Univeral MIDI Packet functionality related to 7-bit SysEx. @@ -33,7 +35,7 @@ namespace universal_midi_packets */ struct SysEx7 { - /* Returns the number of 64-bit packets required to hold a series of + /** Returns the number of 64-bit packets required to hold a series of SysEx bytes. The number passed to this function should exclude the leading/trailing @@ -42,32 +44,34 @@ struct SysEx7 */ static uint32_t getNumPacketsRequiredForDataSize (uint32_t); - /* The different kinds of UMP SysEx-7 message. */ + /** The different kinds of UMP SysEx-7 message. */ enum class Kind : uint8_t { - /* The whole message fits in a single 2-word packet. */ + /** The whole message fits in a single 2-word packet. */ complete = 0, - /* The packet begins a SysEx message that will continue in subsequent packets. */ + /** The packet begins a SysEx message that will continue in subsequent packets. */ begin = 1, - /* The packet is a continuation of an ongoing SysEx message. */ + /** The packet is a continuation of an ongoing SysEx message. */ continuation = 2, - /* The packet terminates an ongoing SysEx message. */ + /** The packet terminates an ongoing SysEx message. */ end = 3 }; - /* Holds the bytes from a single SysEx-7 packet. */ + /** Holds the bytes from a single SysEx-7 packet. */ struct PacketBytes { std::array data; uint8_t size; }; - /* Extracts the data bytes from a 64-bit data message. */ + /** Extracts the data bytes from a 64-bit data message. */ static PacketBytes getDataBytes (const PacketX2& packet); }; } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPUtils.h b/modules/juce_audio_basics/midi/ump/juce_UMPUtils.h index c1599500c8..d55d9cb11e 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPUtils.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPUtils.h @@ -20,25 +20,27 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Helpful types and functions for interacting with Universal MIDI Packets. @tags{Audio} */ struct Utils { - /* Joins 4 bytes into a single 32-bit word. */ + /** Joins 4 bytes into a single 32-bit word. */ static constexpr uint32_t bytesToWord (uint8_t a, uint8_t b, uint8_t c, uint8_t d) { return uint32_t (a << 0x18 | b << 0x10 | c << 0x08 | d << 0x00); } - /* Returns the expected number of 32-bit words in a Universal MIDI Packet, given + /** Returns the expected number of 32-bit words in a Universal MIDI Packet, given the first word of the packet. The result will be between 1 and 4 inclusive. @@ -46,7 +48,7 @@ struct Utils */ static uint32_t getNumWordsForMessageType (uint32_t); - /* + /** Helper functions for setting/getting 4-bit ranges inside a 32-bit word. */ template @@ -65,7 +67,7 @@ struct Utils } }; - /* + /** Helper functions for setting/getting 8-bit ranges inside a 32-bit word. */ template @@ -84,7 +86,7 @@ struct Utils } }; - /* + /** Helper functions for setting/getting 16-bit ranges inside a 32-bit word. */ template @@ -111,3 +113,5 @@ struct Utils } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPView.h b/modules/juce_audio_basics/midi/ump/juce_UMPView.h index 305128319b..3033fc18dd 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPView.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPView.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Points to a single Universal MIDI Packet. The packet must be well-formed for member functions to work correctly. @@ -43,41 +45,41 @@ namespace universal_midi_packets class View { public: - /* Create an invalid view. */ + /** Create an invalid view. */ View() noexcept = default; - /* Create a view of the packet starting at address `d`. */ + /** Create a view of the packet starting at address `d`. */ explicit View (const uint32_t* data) noexcept : ptr (data) {} - /* Get a pointer to the first word in the Universal MIDI Packet currently + /** Get a pointer to the first word in the Universal MIDI Packet currently pointed-to by this view. */ const uint32_t* data() const noexcept { return ptr; } - /* Get the number of 32-words (between 1 and 4 inclusive) in the Universal + /** Get the number of 32-words (between 1 and 4 inclusive) in the Universal MIDI Packet currently pointed-to by this view. */ uint32_t size() const noexcept; - /* Get a specific word from this packet. + /** Get a specific word from this packet. Passing an `index` that is greater than or equal to the result of `size` will cause undefined behaviour. */ const uint32_t& operator[] (size_t index) const noexcept { return ptr[index]; } - /* Get an iterator pointing to the first word in the packet. */ + /** Get an iterator pointing to the first word in the packet. */ const uint32_t* begin() const noexcept { return ptr; } const uint32_t* cbegin() const noexcept { return ptr; } - /* Get an iterator pointing one-past the last word in the packet. */ + /** Get an iterator pointing one-past the last word in the packet. */ const uint32_t* end() const noexcept { return ptr + size(); } const uint32_t* cend() const noexcept { return ptr + size(); } - /* Return true if this view is pointing to the same address as another view. */ + /** Return true if this view is pointing to the same address as another view. */ bool operator== (const View& other) const noexcept { return ptr == other.ptr; } - /* Return false if this view is pointing to the same address as another view. */ + /** Return false if this view is pointing to the same address as another view. */ bool operator!= (const View& other) const noexcept { return ! operator== (other); } private: @@ -86,3 +88,5 @@ private: } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPacket.h b/modules/juce_audio_basics/midi/ump/juce_UMPacket.h index ae4fff3fd5..610e307294 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPacket.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPacket.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Holds a single Universal MIDI Packet. @tags{Audio} @@ -187,3 +189,5 @@ using PacketX4 = Packet<4>; } } + +#endif diff --git a/modules/juce_audio_basics/midi/ump/juce_UMPackets.h b/modules/juce_audio_basics/midi/ump/juce_UMPackets.h index e4dec3a676..b485b100a1 100644 --- a/modules/juce_audio_basics/midi/ump/juce_UMPackets.h +++ b/modules/juce_audio_basics/midi/ump/juce_UMPackets.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** Holds a collection of Universal MIDI Packets. Unlike MidiBuffer, this collection does not store any additional information @@ -39,7 +41,7 @@ namespace universal_midi_packets class Packets { public: - /* Adds a single packet to the collection. + /** Adds a single packet to the collection. The View must be valid for this to work. If the view points to a malformed message, or if the view points to a region @@ -53,24 +55,24 @@ public: void add (const PacketX3& p) { addImpl (p); } void add (const PacketX4& p) { addImpl (p); } - /* Pre-allocates space for at least `numWords` 32-bit words in this collection. */ + /** Pre-allocates space for at least `numWords` 32-bit words in this collection. */ void reserve (size_t numWords) { storage.reserve (numWords); } - /* Removes all previously-added packets from this collection. */ + /** Removes all previously-added packets from this collection. */ void clear() { storage.clear(); } - /* Gets an iterator pointing to the first packet in this collection. */ + /** Gets an iterator pointing to the first packet in this collection. */ Iterator cbegin() const noexcept { return Iterator (data(), size()); } Iterator begin() const noexcept { return cbegin(); } - /* Gets an iterator pointing one-past the last packet in this collection. */ + /** Gets an iterator pointing one-past the last packet in this collection. */ Iterator cend() const noexcept { return Iterator (data() + size(), 0); } Iterator end() const noexcept { return cend(); } - /* Gets a pointer to the contents of the collection as a range of raw 32-bit words. */ + /** Gets a pointer to the contents of the collection as a range of raw 32-bit words. */ const uint32_t* data() const noexcept { return storage.data(); } - /* Returns the number of uint32_t words in storage. + /** Returns the number of uint32_t words in storage. Note that this is likely to be larger than the number of packets currently being stored, as some packets span multiple words. @@ -90,3 +92,5 @@ private: } } + +#endif 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 b7671c3a4d..7adb9bb6b2 100644 --- a/modules/juce_audio_devices/midi_io/ump/juce_UMPBytestreamInputHandler.h +++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPBytestreamInputHandler.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** A base class for classes which convert bytestream midi to other formats. @tags{Audio} @@ -38,7 +40,7 @@ struct BytestreamInputHandler virtual void pushMidiData (const void* data, int bytes, double time) = 0; }; -/* +/** Parses a continuous bytestream and emits complete MidiMessages whenever a full message is received. @@ -49,7 +51,7 @@ 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. @@ -87,7 +89,7 @@ struct BytestreamToBytestreamHandler : public BytestreamInputHandler MidiDataConcatenator concatenator; }; -/* +/** Parses a continuous MIDI 1.0 bytestream, and emits full messages in the requested UMP format. @@ -98,7 +100,7 @@ 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. @@ -138,3 +140,5 @@ struct BytestreamToUMPHandler : public BytestreamInputHandler } } + +#endif 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 2b09ba66bb..89b175430b 100644 --- a/modules/juce_audio_devices/midi_io/ump/juce_UMPU32InputHandler.h +++ b/modules/juce_audio_devices/midi_io/ump/juce_UMPU32InputHandler.h @@ -20,12 +20,14 @@ ============================================================================== */ +#ifndef DOXYGEN + namespace juce { namespace universal_midi_packets { -/* +/** A base class for classes which convert Universal MIDI Packets to other formats. @@ -39,7 +41,7 @@ struct U32InputHandler virtual void pushMidiData (const uint32_t* begin, const uint32_t* end, double time) = 0; }; -/* +/** Parses a continuous stream of U32 words and emits complete MidiMessages whenever a full message is received. @@ -50,7 +52,7 @@ 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. @@ -91,7 +93,7 @@ struct U32ToBytestreamHandler : public U32InputHandler ToBytestreamDispatcher dispatcher; }; -/* +/** Parses a continuous stream of U32 words and emits full messages in the requested UMP format. @@ -102,7 +104,7 @@ 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. @@ -149,3 +151,5 @@ struct U32ToUMPHandler : public U32InputHandler } } + +#endif