Skip to content

Commit a551ae7

Browse files
LucHeartLucHeart
authored
Merge pull request #7 from LucHeart/codex/add-comments-to-all-function-definitions
Add XML documentation for OSC interfaces and implementations
2 parents 201b61d + 68a77da commit a551ae7

File tree

12 files changed

+83
-0
lines changed

12 files changed

+83
-0
lines changed

‎CoreOSC/IOscListener.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,36 @@
44

55
namespace LucHeart.CoreOSC;
66

7+
/// <summary>
8+
/// Provides asynchronous operations for receiving OSC messages and bundles.
9+
/// </summary>
710
public interface IOscListener
811
{
12+
/// <summary>
13+
/// Receives the next OSC message from the listening endpoint.
14+
/// </summary>
15+
/// <param name="ct">A token used to cancel the receive operation.</param>
16+
/// <returns>A task that resolves to the next <see cref="OscMessage"/>.</returns>
917
public Task<OscMessage> ReceiveMessageAsync(CancellationToken ct);
1018

19+
/// <summary>
20+
/// Receives the next OSC message together with the originating endpoint information.
21+
/// </summary>
22+
/// <param name="ct">A token used to cancel the receive operation.</param>
23+
/// <returns>A task that resolves to the received <see cref="OscMessage"/> and its sender endpoint.</returns>
1124
public Task<(OscMessage Message, IPEndPoint EndPoint)> ReceiveMessageExAsync(CancellationToken ct);
1225

26+
/// <summary>
27+
/// Receives the next OSC bundle from the listening endpoint.
28+
/// </summary>
29+
/// <param name="ct">A token used to cancel the receive operation.</param>
30+
/// <returns>A task that resolves to the next <see cref="OscBundle"/>.</returns>
1331
public Task<OscBundle> ReceiveBundleAsync(CancellationToken ct);
1432

33+
/// <summary>
34+
/// Receives the next OSC bundle together with the originating endpoint information.
35+
/// </summary>
36+
/// <param name="ct">A token used to cancel the receive operation.</param>
37+
/// <returns>A task that resolves to the received <see cref="OscBundle"/> and its sender endpoint.</returns>
1538
public Task<(OscBundle Bundle, IPEndPoint EndPoint)> ReceiveBundleExAsync(CancellationToken ct);
1639
}

‎CoreOSC/IOscPacket.cs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
namespace LucHeart.CoreOSC;
22

3+
/// <summary>
4+
/// Represents an Open Sound Control packet that can be serialized for transmission.
5+
/// </summary>
36
public interface IOscPacket
47
{
8+
/// <summary>
9+
/// Converts the packet into its OSC binary representation.
10+
/// </summary>
11+
/// <returns>The serialized OSC byte sequence.</returns>
512
public byte[] GetBytes();
613
}

‎CoreOSC/IOscSender.cs‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,38 @@
33

44
namespace LucHeart.CoreOSC;
55

6+
/// <summary>
7+
/// Provides asynchronous operations for sending OSC packets to remote endpoints.
8+
/// </summary>
69
public interface IOscSender
710
{
11+
/// <summary>
12+
/// Sends a raw OSC message payload to the configured default endpoint.
13+
/// </summary>
14+
/// <param name="message">The binary OSC message payload to send.</param>
15+
/// <returns>A task that represents the asynchronous send operation.</returns>
816
public Task SendAsync(byte[] message);
917

18+
/// <summary>
19+
/// Serializes and sends an OSC packet to the configured default endpoint.
20+
/// </summary>
21+
/// <param name="packet">The OSC packet to serialize and send.</param>
22+
/// <returns>A task that represents the asynchronous send operation.</returns>
1023
public Task SendAsync(IOscPacket packet);
1124

25+
/// <summary>
26+
/// Sends a raw OSC message payload to a specific endpoint.
27+
/// </summary>
28+
/// <param name="endPoint">The destination endpoint that should receive the message.</param>
29+
/// <param name="message">The binary OSC message payload to send.</param>
30+
/// <returns>A task that represents the asynchronous send operation.</returns>
1231
public Task SendAsync(IPEndPoint endPoint, byte[] message);
1332

33+
/// <summary>
34+
/// Serializes and sends an OSC packet to a specific endpoint.
35+
/// </summary>
36+
/// <param name="endPoint">The destination endpoint that should receive the packet.</param>
37+
/// <param name="packet">The OSC packet to serialize and send.</param>
38+
/// <returns>A task that represents the asynchronous send operation.</returns>
1439
public Task SendAsync(IPEndPoint endPoint, IOscPacket packet);
1540
}

‎CoreOSC/IOscSerializable.cs‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
namespace LucHeart.CoreOSC;
22

3+
/// <summary>
4+
/// Represents a value that can be serialized into the OSC binary wire format.
5+
/// </summary>
36
public interface IOscSerializable
47
{
8+
/// <summary>
9+
/// Converts the current value into its OSC binary representation.
10+
/// </summary>
11+
/// <returns>The serialized OSC byte sequence.</returns>
512
public byte[] ToBytes();
613
}

‎CoreOSC/Midi.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ public Midi(byte port, byte status, byte data1, byte data2)
2828
public override int GetHashCode() => (Port << 24) + (Status << 16) + (Data1 << 8) + (Data2);
2929

3030

31+
/// <inheritdoc />
3132
public byte[] ToBytes()
3233
{
3334
var output = new byte[4];

‎CoreOSC/OscBundle.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ public OscBundle(ulong timetag, params OscMessage[] args)
3333
private const string BundleName = "#bundle";
3434
private static readonly int BundleTagLen = Utils.AlignedStringLength(BundleName);
3535

36+
/// <inheritdoc />
3637
public byte[] GetBytes()
3738
{
3839
var outMessages = Messages.Select(msg => msg.GetBytes()).ToArray();

‎CoreOSC/OscDuplex.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,15 @@ public OscDuplex(IPEndPoint listenerEndpoint, IPEndPoint remoteEndpoint) : base(
1212
_remoteEndPoint = remoteEndpoint;
1313
}
1414

15+
/// <inheritdoc />
1516
public Task SendAsync(byte[] message) => UdpClient.SendAsync(message, message.Length, _remoteEndPoint);
1617

18+
/// <inheritdoc />
1719
public Task SendAsync(IOscPacket packet) => SendAsync(packet.GetBytes());
1820

21+
/// <inheritdoc />
1922
public Task SendAsync(IPEndPoint endPoint, byte[] message) => UdpClient.SendAsync(message, message.Length, endPoint);
2023

24+
/// <inheritdoc />
2125
public Task SendAsync(IPEndPoint endPoint, IOscPacket packet) => SendAsync(endPoint, packet.GetBytes());
2226
}

‎CoreOSC/OscListener.cs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,11 @@ public OscListener(IPEndPoint listenerEndPoint)
4343
}
4444
}
4545

46+
/// <inheritdoc />
47+
/// <remarks>
48+
/// When <see cref="EnableTransparentBundleToMessageConversion"/> is <see langword="true"/>, bundle contents are
49+
/// transparently dequeued and returned as individual messages.
50+
/// </remarks>
4651
public async Task<OscMessage> ReceiveMessageAsync(CancellationToken ct = default)
4752
{
4853
if (EnableTransparentBundleToMessageConversion)
@@ -76,6 +81,7 @@ public async Task<OscMessage> ReceiveMessageAsync(CancellationToken ct = default
7681
}
7782
}
7883

84+
/// <inheritdoc />
7985
public async Task<(OscMessage Message, IPEndPoint EndPoint)> ReceiveMessageExAsync(CancellationToken ct = default)
8086
{
8187
#if !NETSTANDARD
@@ -86,6 +92,7 @@ public async Task<OscMessage> ReceiveMessageAsync(CancellationToken ct = default
8692
return (OscMessage.ParseMessage(receiveResult.Buffer), receiveResult.RemoteEndPoint);
8793
}
8894

95+
/// <inheritdoc />
8996
public async Task<OscBundle> ReceiveBundleAsync(CancellationToken ct = default)
9097
{
9198
#if !NETSTANDARD
@@ -96,6 +103,7 @@ public async Task<OscBundle> ReceiveBundleAsync(CancellationToken ct = default)
96103
return OscBundle.ParseBundle(receiveResult.Buffer);
97104
}
98105

106+
/// <inheritdoc />
99107
public async Task<(OscBundle Bundle, IPEndPoint EndPoint)> ReceiveBundleExAsync(CancellationToken ct = default)
100108
{
101109
#if !NETSTANDARD

‎CoreOSC/OscMessage.cs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ public OscMessage(string address, params object?[] args)
1717
Arguments = args;
1818
}
1919

20+
/// <inheritdoc />
2021
public byte[] GetBytes()
2122
{
2223
var parts = new List<byte[]>();

‎CoreOSC/OscSender.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,16 @@ public OscSender(IPEndPoint remoteIpEndPoint)
1717
_sock = new Socket(AddressFamily.InterNetwork, SocketType.Dgram, ProtocolType.Udp);
1818
}
1919

20+
/// <inheritdoc />
2021
public Task SendAsync(byte[] message) => _sock.SendToAsync(message, SocketFlags.None, _remoteIpEndPoint);
2122

23+
/// <inheritdoc />
2224
public Task SendAsync(IOscPacket packet) => SendAsync(packet.GetBytes());
2325

26+
/// <inheritdoc />
2427
public Task SendAsync(IPEndPoint endPoint, byte[] message) => _sock.SendToAsync(message, SocketFlags.None, endPoint);
2528

29+
/// <inheritdoc />
2630
public Task SendAsync(IPEndPoint endPoint, IOscPacket packet) => SendAsync(endPoint, packet.GetBytes());
2731

2832
public void Dispose()

0 commit comments

Comments
 (0)