Reland "Add documentation, tests and simplify webrtc::SimulatedNetwork."

This is a reland of commit c1d5fda22c8ae456950c5549d22d099b478c67e2

Original change's description:
> Add documentation, tests and simplify webrtc::SimulatedNetwork.
>
> This CL increases the test coverage for webrtc::SimualtedNetwork, adds
> some more comments to the class and the interface it implements and
> simplify the logic around capacity and delay management in the
> simulated network.
>
> More CLs will follow to continue the refactoring but this is the
> ground work to make this more modular in the future.
>
> Bug: webrtc:14525, b/243202138
> Change-Id: Ib0408cf6e2c1cdceb71f8bec3202d2960c5b4d3c
> Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/278042
> Reviewed-by: Artem Titov <titovartem@webrtc.org>
> Reviewed-by: Per Kjellander <perkj@webrtc.org>
> Reviewed-by: Rasmus Brandt <brandtr@webrtc.org>
> Commit-Queue: Mirko Bonadei <mbonadei@webrtc.org>
> Reviewed-by: Björn Terelius <terelius@webrtc.org>
> Cr-Commit-Position: refs/heads/main@{#38388}

Bug: webrtc:14525, b/243202138, b/256595485
Change-Id: Iaf8160eb8f8e29034b8f98e81ce07eb608663d30
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/280963
Reviewed-by: Rasmus Brandt <brandtr@webrtc.org>
Commit-Queue: Mirko Bonadei <mbonadei@webrtc.org>
Reviewed-by: Artem Titov <titovartem@webrtc.org>
Reviewed-by: Per Kjellander <perkj@webrtc.org>
Cr-Commit-Position: refs/heads/main@{#38557}

api/test/simulated_network.h

@@ -38,6 +38,12 @@ struct PacketDeliveryInfo {
   static constexpr int kNotReceived = -1;
   PacketDeliveryInfo(PacketInFlightInfo source, int64_t receive_time_us)
       : receive_time_us(receive_time_us), packet_id(source.packet_id) {}
+
+  bool operator==(const PacketDeliveryInfo& other) const {
+    return receive_time_us == other.receive_time_us &&
+           packet_id == other.packet_id;
+  }
+
   int64_t receive_time_us;
   uint64_t packet_id;
 };
@@ -64,14 +70,50 @@ struct BuiltInNetworkBehaviorConfig {
   int packet_overhead = 0;
 };
 
+// Interface that represents a Network behaviour.
+//
+// It is clients of this interface responsibility to enqueue and dequeue
+// packets (based on the estimated delivery time expressed by
+// NextDeliveryTimeUs).
+//
+// To enqueue packets, call EnqueuePacket:
+// EXPECT_TRUE(network.EnqueuePacket(
+//     PacketInFlightInfo(/*size=*/1, /*send_time_us=*/0, /*packet_id=*/1)));
+//
+// To know when to call DequeueDeliverablePackets to pull packets out of the
+// network, call NextDeliveryTimeUs and schedule a task to invoke
+// DequeueDeliverablePackets (if not already scheduled).
+//
+// DequeueDeliverablePackets will return a vector of delivered packets, but this
+// vector can be empty in case of extra delay. In such case, make sure to invoke
+// NextDeliveryTimeUs and schedule a task to call DequeueDeliverablePackets for
+// the next estimated delivery of packets.
+//
+// std::vector<PacketDeliveryInfo> delivered_packets =
+//     network.DequeueDeliverablePackets(/*receive_time_us=*/1000000);
 class NetworkBehaviorInterface {
  public:
+  // Enqueues a packet in the network and returns true if the action was
+  // successful, false otherwise (for example, because the network capacity has
+  // been saturated). If the return value is false, the packet should be
+  // considered as dropped and it will not be returned by future calls
+  // to DequeueDeliverablePackets.
+  // Packets enqueued will exit the network when DequeueDeliverablePackets is
+  // called and enough time has passed (see NextDeliveryTimeUs).
   virtual bool EnqueuePacket(PacketInFlightInfo packet_info) = 0;
   // Retrieves all packets that should be delivered by the given receive time.
+  // Not all the packets in the returned std::vector are actually delivered.
+  // In order to know the state of each packet it is necessary to check the
+  // `receive_time_us` field of each packet. If that is set to
+  // PacketDeliveryInfo::kNotReceived then the packet is considered lost in the
+  // network.
   virtual std::vector<PacketDeliveryInfo> DequeueDeliverablePackets(
       int64_t receive_time_us) = 0;
   // Returns time in microseconds when caller should call
-  // DequeueDeliverablePackets to get next set of packets to deliver.
+  // DequeueDeliverablePackets to get the next set of delivered packets. It is
+  // possible that no packet will be delivered by that time (e.g. in case of
+  // random extra delay), in such case this method should be called again to get
+  // the updated estimated delivery time.
   virtual absl::optional<int64_t> NextDeliveryTimeUs() const = 0;
   virtual ~NetworkBehaviorInterface() = default;
 };
@@ -81,10 +123,14 @@ class NetworkBehaviorInterface {
 // capacity introduced delay.
 class SimulatedNetworkInterface : public NetworkBehaviorInterface {
  public:
-  // Sets a new configuration. This won't affect packets already in the pipe.
+  // Sets a new configuration.
   virtual void SetConfig(const BuiltInNetworkBehaviorConfig& config) = 0;
   virtual void UpdateConfig(
       std::function<void(BuiltInNetworkBehaviorConfig*)> config_modifier) = 0;
+  // Pauses the network until `until_us`. This affects both delivery (calling
+  // DequeueDeliverablePackets before `until_us` results in an empty std::vector
+  // of packets) and capacity (the network is paused, so packets are not
+  // flowing and they will restart flowing at `until_us`).
   virtual void PauseTransmissionUntil(int64_t until_us) = 0;
 };