From 378ff7aa119b3a5c9fe7cb7ddf06c714b013286e Mon Sep 17 00:00:00 2001
From: Victor Gaydov <victor@enise.org>
Date: Wed, 31 May 2023 17:31:36 +0400
Subject: [PATCH] Refine comments and validation for some config fields

---
 .../org/rocstreaming/roctoolkit/Check.java    |  7 +++++
 .../roctoolkit/RocContextConfig.java          |  7 +++--
 .../roctoolkit/RocReceiverConfig.java         | 31 ++++++++++++++-----
 .../roctoolkit/RocSenderConfig.java           | 29 +++++++++++------
 .../org/rocstreaming/roctoolkit/Slot.java     |  3 ++
 5 files changed, 58 insertions(+), 19 deletions(-)

diff --git a/src/main/java/org/rocstreaming/roctoolkit/Check.java b/src/main/java/org/rocstreaming/roctoolkit/Check.java
index dddb8f58..1714f32c 100644
--- a/src/main/java/org/rocstreaming/roctoolkit/Check.java
+++ b/src/main/java/org/rocstreaming/roctoolkit/Check.java
@@ -24,4 +24,11 @@ static int notNegative(int value, String name) {
         }
         return value;
     }
+
+    static long notNegative(long value, String name) {
+        if (value < 0) {
+            throw new IllegalArgumentException(name + " must not be negative");
+        }
+        return value;
+    }
 }
diff --git a/src/main/java/org/rocstreaming/roctoolkit/RocContextConfig.java b/src/main/java/org/rocstreaming/roctoolkit/RocContextConfig.java
index 9d8e77fa..4b31fe8c 100644
--- a/src/main/java/org/rocstreaming/roctoolkit/RocContextConfig.java
+++ b/src/main/java/org/rocstreaming/roctoolkit/RocContextConfig.java
@@ -19,7 +19,8 @@ public class RocContextConfig {
      * Maximum size in bytes of a network packet.
      * Defines the amount of bytes allocated per network packet.
      * Sender and receiver won't handle packets larger than this.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private int maxPacketSize;
 
@@ -27,7 +28,9 @@ public class RocContextConfig {
      * Maximum size in bytes of an audio frame.
      * Defines the amount of bytes allocated per intermediate internal
      * frame in the pipeline. Does not limit the size of the frames
-     * provided by user. If zero, default value is used.
+     * provided by user.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private int maxFrameSize;
 
diff --git a/src/main/java/org/rocstreaming/roctoolkit/RocReceiverConfig.java b/src/main/java/org/rocstreaming/roctoolkit/RocReceiverConfig.java
index e4f1c03c..7b3fe524 100644
--- a/src/main/java/org/rocstreaming/roctoolkit/RocReceiverConfig.java
+++ b/src/main/java/org/rocstreaming/roctoolkit/RocReceiverConfig.java
@@ -18,34 +18,39 @@ public class RocReceiverConfig {
     /**
      * The rate of the samples in the frames returned to the user.
      * Number of samples per channel per second.
+     * Should be set to a positive value.
      */
     private int frameSampleRate;
 
     /**
      * The channel set in the frames returned to the user.
+     * Should be set to a non-null value.
      */
     private ChannelSet frameChannels;
 
     /**
      * The sample encoding in the frames returned to the user.
+     * Should be set to a non-null value.
      */
     private FrameEncoding frameEncoding;
 
     /**
      * Clock source to use.
      * Defines whether read operation will be blocking or non-blocking.
-     * If zero, default value is used.
+     * If null or unset, default value is used.
      */
     private ClockSource clockSource;
 
     /**
      * Resampler backend to use.
+     * If null or unset, default value is used.
      */
     private ResamplerBackend resamplerBackend;
 
     /**
      * Resampler profile to use.
-     * If non-zero, the receiver employs resampler for two purposes:
+     * If null or unset, default value is used.
+     * If resampling is enabled, the receiver employs resampler for two purposes:
      * <ul>
      *     <li>
      *         adjust the sender clock to the receiver clock, which
@@ -65,7 +70,8 @@ public class RocReceiverConfig {
      * requested latency.
      * Then, if resampler is enabled, the session will adjust its clock
      * to keep actual latency as close as possible to the target latency.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private long targetLatency;
 
@@ -73,7 +79,8 @@ public class RocReceiverConfig {
      * Maximum delta between current and target latency, in nanoseconds.
      * If current latency becomes larger than the target latency plus
      * this value, the session is terminated.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private long maxLatencyOverrun;
 
@@ -84,7 +91,8 @@ public class RocReceiverConfig {
      * May be larger than the target latency because current latency may
      * be negative, which means that the playback run ahead of the last
      * packet received from network.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private long maxLatencyUnderrun;
 
@@ -93,7 +101,8 @@ public class RocReceiverConfig {
      * If there is no playback during this period, the session is terminated.
      * This mechanism allows to detect dead, hanging, or broken clients
      * generating invalid packets.
-     * If zero, default value is used. If negative, the timeout is disabled.
+     * If zero or unset, default value is used.
+     * If negative, the timeout is disabled.
      */
     private long noPlaybackTimeout;
 
@@ -106,13 +115,15 @@ public class RocReceiverConfig {
      * This mechanism allows to detect vicious circles like when all
      * client packets are a bit late and receiver constantly drops them
      * producing unpleasant noise.
-     * If zero, default value is used. If negative, the timeout is disabled.
+     * If zero or unset, default value is used.
+     * If negative, the timeout is disabled.
      */
     private long brokenPlaybackTimeout;
 
     /**
      * Breakage detection window, in nanoseconds.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      *
      * @see ConfigBuilder#brokenPlaybackTimeout
      */
@@ -128,6 +139,10 @@ public RocReceiverConfig build() {
             Check.notNegative(super.frameSampleRate, "frameSampleRate");
             Check.notNull(super.frameChannels, "frameChannels");
             Check.notNull(super.frameEncoding, "frameEncoding");
+            Check.notNegative(super.targetLatency, "targetLatency");
+            Check.notNegative(super.maxLatencyUnderrun, "maxLatencyUnderrun");
+            Check.notNegative(super.maxLatencyUnderrun, "maxLatencyUnderrun");
+            Check.notNegative(super.breakageDetectionWindow, "breakageDetectionWindow");
             return super.build();
         }
     }
diff --git a/src/main/java/org/rocstreaming/roctoolkit/RocSenderConfig.java b/src/main/java/org/rocstreaming/roctoolkit/RocSenderConfig.java
index dc544b06..aaefd159 100644
--- a/src/main/java/org/rocstreaming/roctoolkit/RocSenderConfig.java
+++ b/src/main/java/org/rocstreaming/roctoolkit/RocSenderConfig.java
@@ -18,35 +18,39 @@ public class RocSenderConfig {
     /**
      * The rate of the samples in the frames returned to the user.
      * Number of samples per channel per second.
+     * Should be set to a positive value.
      */
     private int frameSampleRate;
 
     /**
      * The channel set in the frames returned to the user.
+     * Should be set to a non-null value.
      */
     private ChannelSet frameChannels;
 
     /**
      * The sample encoding in the frames returned to the user.
+     * Should be set to a non-null value.
      */
     private FrameEncoding frameEncoding;
 
     /**
      * The rate of the samples in the packets generated by sender.
      * Number of samples per channel per second.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private int packetSampleRate;
 
     /**
      * The channel set in the packets generated by sender.
-     * If null, default value is used.
+     * If null or unset, default value is used.
      */
     private ChannelSet packetChannels;
 
     /**
      * The sample encoding in the packets generated by sender.
-     * If null, default value is used.
+     * If null or unset, default value is used.
      */
     private PacketEncoding packetEncoding;
 
@@ -56,7 +60,8 @@ public class RocSenderConfig {
      * The samples written to the sender are buffered until the full
      * packet is accumulated or the sender is flushed or closed.
      * Larger number reduces packet overhead but also increases latency.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private long packetLength;
 
@@ -70,25 +75,28 @@ public class RocSenderConfig {
     /**
      * Clock source to use.
      * Defines whether write operation will be blocking or non-blocking.
-     * If zero, default value is used.
+     * If null or unset, default value is used.
      */
     private ClockSource clockSource;
 
     /**
      * Resampler backend to use.
+     * If null or unset, default value is used.
      */
     private ResamplerBackend resamplerBackend;
 
     /**
      * Resampler profile to use.
-     * If non-null, the sender employs resampler if the frame sample rate
+     * If null or unset, default value is used.
+     * If resampling is enabled, the sender employs resampler if the frame sample rate
      * differs from the packet sample rate.
      */
     private ResamplerProfile resamplerProfile;
 
     /**
      * FEC encoding to use.
-     * If non-null, the sender employs a FEC codec to generate redundant
+     * If null or unset, default value is used.
+     * If FEC is enabled, the sender employs a FEC codec to generate redundant
      * packets which may be used on receiver to restore lost packets.
      * This requires both sender and receiver to use two separate source
      * and repair ports.
@@ -99,7 +107,8 @@ public class RocSenderConfig {
      * Number of source packets per FEC block.
      * Used if some FEC encoding is selected.
      * Larger number increases robustness but also increases latency.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private int fecBlockSourcePackets;
 
@@ -107,7 +116,8 @@ public class RocSenderConfig {
      * Number of repair packets per FEC block.
      * Used if some FEC encoding is selected.
      * Larger number increases robustness but also increases traffic.
-     * If zero, default value is used.
+     * If zero or unset, default value is used.
+     * Should not be negative.
      */
     private int fecBlockRepairPackets;
 
@@ -122,6 +132,7 @@ public RocSenderConfig build() {
             Check.notNull(super.frameChannels, "frameChannels");
             Check.notNull(super.frameEncoding, "frameEncoding");
             Check.notNegative(super.packetSampleRate, "packetSampleRate");
+            Check.notNegative(super.packetLength, "packetLength");
             Check.notNegative(super.fecBlockSourcePackets, "fecBlockSourcePackets");
             Check.notNegative(super.fecBlockRepairPackets, "fecBlockRepairPackets");
             return super.build();
diff --git a/src/main/java/org/rocstreaming/roctoolkit/Slot.java b/src/main/java/org/rocstreaming/roctoolkit/Slot.java
index fc36d076..4ec6d61f 100644
--- a/src/main/java/org/rocstreaming/roctoolkit/Slot.java
+++ b/src/main/java/org/rocstreaming/roctoolkit/Slot.java
@@ -22,6 +22,9 @@
 @EqualsAndHashCode
 public class Slot {
 
+    /**
+     * Alias for the slot with index zero.
+     */
     public static final Slot DEFAULT = new Slot(0);
 
     private final int value;