Improve pipeline test comments

Author: gavv

src/tests/roc_pipeline/test_helpers/control_writer.h

@@ -24,6 +24,7 @@ namespace roc {
 namespace pipeline {
 namespace test {
 
+// Generates control packets and pass them to destination writer
 class ControlWriter : public core::NonCopyable<> {
 public:
     ControlWriter(packet::IWriter& writer,

src/tests/roc_pipeline/test_helpers/frame_reader.h

@@ -23,6 +23,7 @@ namespace roc {
 namespace pipeline {
 namespace test {
 
+// Read audio frames from source and validate
 class FrameReader : public core::NonCopyable<> {
 public:
     FrameReader(sndio::ISource& source,

src/tests/roc_pipeline/test_helpers/frame_writer.h

@@ -22,6 +22,7 @@ namespace roc {
 namespace pipeline {
 namespace test {
 
+// Generate audio frames and write to sink
 class FrameWriter : public core::NonCopyable<> {
 public:
     FrameWriter(sndio::ISink& sink, core::BufferFactory<audio::sample_t>& buffer_factory)

src/tests/roc_pipeline/test_helpers/packet_proxy.h

@@ -21,6 +21,9 @@ namespace roc {
 namespace pipeline {
 namespace test {
 
+// Copy sequence of packets to multiple writers
+// Routes packet by type
+// Clears packet meta-data as if packet was delivered over network
 class PacketProxy : public packet::IWriter, core::NonCopyable<> {
 public:
     PacketProxy(packet::PacketFactory& packet_factory,
@@ -79,9 +82,10 @@ class PacketProxy : public packet::IWriter, core::NonCopyable<> {
     }
 
 private:
-    // creates a new packet with the same buffer, clearing all meta-information
-    // like flags, parsed fields, etc; this way we simulate delivering packet
-    // over network
+    // creates a new packet with the same buffer, without copying any meta-information
+    // like flags, parsed fields, etc; this way we simulate that packet was "delivered"
+    // over network - packets enters receiver's pipeline without any meta-information,
+    // and receiver fills that meta-information using packet parsers
     packet::PacketPtr copy_packet_(const packet::PacketPtr& pa) {
         packet::PacketPtr pb = packet_factory_.new_packet();
         CHECK(pb);

src/tests/roc_pipeline/test_helpers/packet_reader.h

@@ -27,7 +27,7 @@ namespace roc {
 namespace pipeline {
 namespace test {
 
-//! Reads, parses, and validates packets.
+// Read, parse, and validates packets
 class PacketReader : public core::NonCopyable<> {
 public:
     PacketReader(core::IArena& arena,

src/tests/roc_pipeline/test_helpers/packet_writer.h

@@ -34,10 +34,10 @@ namespace roc {
 namespace pipeline {
 namespace test {
 
-//! Generates and writes packets.
+// Generates source and repair packets and pass them to destination writers
 class PacketWriter : public core::NonCopyable<> {
 public:
-    //! Initialize without FEC.
+    // Initialize without FEC (produce only source packets)
     PacketWriter(core::IArena& arena,
                  packet::IWriter& dst_writer,
                  rtp::FormatMap& format_map,
@@ -63,7 +63,7 @@ class PacketWriter : public core::NonCopyable<> {
                    packet::FEC_None, fec::WriterConfig());
     }
 
-    //! Initialize with FEC.
+    // Initialize with FEC (produce source + repair packets)
     PacketWriter(core::IArena& arena,
                  packet::IWriter& source_dst_writer,
                  packet::IWriter& repair_dst_writer,
@@ -220,9 +220,12 @@ class PacketWriter : public core::NonCopyable<> {
     void deliver_packet_(const packet::PacketPtr& pp) {
         if (fec_writer_) {
             // fec_writer will produce source and repair packets and store in fec_queue
+            // note that we're calling copy_packet_() only after fec_writer, because
+            // fec writer normally lives in the middle of the pipeline and expects
+            // packets to have all necessary meta-information
             fec_writer_->write(pp);
 
-            // deliver produced packets
+            // compose and "deliver" source and repair packets produced by fec_writer
             packet::PacketPtr fp;
             while (fec_queue_.read(fp) == status::StatusOK) {
                 if (fp->has_flags(packet::Packet::FlagAudio)) {
@@ -234,14 +237,16 @@ class PacketWriter : public core::NonCopyable<> {
                 }
             }
         } else {
+            // compose and "deliver" packet
             CHECK(source_composer_->compose(*pp));
             source_writer_->write(copy_packet_(pp));
         }
     }
 
-    // creates a new packet with the same buffer, clearing all meta-information
-    // like flags, parsed fields, etc; this way we simulate delivering packet
-    // over network
+    // creates a new packet with the same buffer, without copying any meta-information
+    // like flags, parsed fields, etc; this way we simulate that packet was "delivered"
+    // over network - packets enters receiver's pipeline without any meta-information,
+    // and receiver fills that meta-information using packet parsers
     packet::PacketPtr copy_packet_(const packet::PacketPtr& pa) {
         packet::PacketPtr pb = packet_factory_.new_packet();
         CHECK(pb);

src/tests/roc_pipeline/test_receiver_source.cpp

@@ -21,6 +21,24 @@
 #include "roc_pipeline/receiver_source.h"
 #include "roc_rtp/format_map.h"
 
+// This file contains tests for ReceiverSource. ReceiverSource can be seen as a big
+// composite processor (consisting of chanined smaller processors) that transforms
+// network packets into audio frames. Typically, network thread writes packets into
+// ReceiverSource, and sound card thread read frames from it.
+//
+// Each test in this file prepares a sequence of input packets and checks what sequence
+// of output frames receiver produces in response. Each test checks one aspect of
+// pipeline behavior, e.g. handling packet reordering, recovering lost packets, mixing
+// multiple sessions, etc.
+//
+// The tests mostly use three helper classes:
+//  - test::PacketWriter - to produce source (RTP) and repair (FEC) packets
+//  - test::ControlWriter - to produce control packets (RTCP)
+//  - test::FrameReader - to retrieve and validate audio frames
+//
+// test::PacketWriter and test::ControlWriter simulate remote sender that produces
+// packets, and test::FrameReader simulates local sound card that consumes frames.
+
 namespace roc {
 namespace pipeline {
 
@@ -2059,7 +2077,6 @@ TEST(receiver_source, metrics_truncation) {
 
         UNSIGNED_LONGS_EQUAL(2, slot_metrics.num_sessions);
         UNSIGNED_LONGS_EQUAL(2, sess_metrics_size);
-
         CHECK(sess_metrics[0].latency.niq_latency > 0);
         CHECK(sess_metrics[1].latency.niq_latency > 0);
         CHECK(sess_metrics[2].latency.niq_latency == 0);

src/tests/roc_pipeline/test_sender_sink.cpp

@@ -19,6 +19,22 @@
 #include "roc_pipeline/sender_sink.h"
 #include "roc_rtp/format_map.h"
 
+// This file contains tests for SenderSink. SenderSink can be seen as a big
+// composite processor (consisting of chanined smaller processors) that transforms
+// audio frames into network packets. Typically, sound card thread writes frames
+// to SenderSink, and it in turn writes packets to network thread.
+//
+// Each test in this file prepares a sequence of input frames and checks what sequence
+// of output packets sender produces in response. Each test checks one aspect of
+// pipeline behavior, e.g. splitting frames into packets, transcoding, etc.
+//
+// The tests mostly use two helper classes:
+//  - test::FrameWriter - to produce frames
+//  - test::PacketReader - to retrieve and validate packets
+//
+// test::FrameWriter simulates local sound card that produces frames, and
+// test::PacketReader simulates remote receiver that consumes packets.
+
 namespace roc {
 namespace pipeline {
 

src/tests/roc_pipeline/test_sender_sink_receiver_source.cpp

@@ -26,6 +26,27 @@
 namespace roc {
 namespace pipeline {
 
+// This file contains integration tests that combine SenderSink and ReceiverSource.
+//
+// SenderSink consumes audio frames and produces network packets. ReceiverSource
+// consumes network packets and produces audio frames.
+//
+// Each test in this file prepares a sequence of input frames, passes it to
+// SenderSink, transfers packets produced by SenderSink to ReceiverSource, and
+// checks what sequence of output frames ReceiverSource produced in response.
+//
+// Normally SenderSink and ReceiverSource are not connected directly. We simulate
+// delivering packets over network by re-creating packets for receiver with the
+// same buffer but with stripped meta-information.
+//
+// The tests use three helper classes:
+//  - test::FrameWriter - to produce frames
+//  - test::PacketProxy - to simulate delivery of packets from sender to receiver
+//  - test::FrameReader - to retrieve and validate frames
+//
+// test::FrameWriter simulates sender sound card that produces frames, and
+// test::FrameReader simulates receiver sound card that consumes frames.
+
 namespace {
 
 const audio::ChannelMask Chans_Mono = audio::ChanMask_Surround_Mono;