Fixing inconsistency with behavior of `ClearGettingPorts`.

webrtc/p2p/base/portallocator.h

 /*
  *  Copyright 2004 The WebRTC Project Authors. All rights reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 140 matching lines @@
   const std::string& ice_pwd() const { return ice_pwd_; }
   bool pooled() const { return ice_ufrag_.empty(); }
 
   // Setting this filter should affect not only candidates gathered in the
   // future, but candidates already gathered and ports already "ready",
   // which would be returned by ReadyCandidates() and ReadyPorts().
   //
   // Default filter should be CF_ALL.
   virtual void SetCandidateFilter(uint32_t filter) = 0;
 
-  // Starts gathering STUN and Relay configurations.
+  // Starts gathering ports and ICE candidates.
   virtual void StartGettingPorts() = 0;
-  // Completely stops the gathering process and will not start new ones.
+  // Completely stops gathering. Will not gather again unless StartGettingPorts
+  // is called again.
   virtual void StopGettingPorts() = 0;
   // Whether the session is actively getting ports.
   virtual bool IsGettingPorts() = 0;
-  // ClearGettingPorts and IsCleared are used by continual gathering.
-  // Only stops the existing gathering process but may start new ones if needed.
+
+  //
+  // NOTE: The group of methods below is only used for continual gathering.
+  //
+
+  // ClearGettingPorts should have the same immediate effect as
+  // StopGettingPorts, but if the implementation supports continual gathering,
+  // ClearGettingPorts allows additional ports/candidates to be gathered if the
+  // network conditions change.
   virtual void ClearGettingPorts() = 0;
   // Whether it is in the state where the existing gathering process is stopped,
   // but new ones may be started (basically after calling ClearGettingPorts).
   virtual bool IsCleared() const { return false; }
   // Whether the session has completely stopped.
   virtual bool IsStopped() const { return false; }
   // Re-gathers candidates on networks that do not have any connections. More
   // precisely, a network interface may have more than one IP addresses (e.g.,
   // IPv4 and IPv6 addresses). Each address subnet will be used to create a
   // network. Only if all networks of an interface have no connection, the
@@ skipping 210 matching lines @@
   // This variable represents the total number of pooled sessions
   // both owned by this class and taken by TakePooledSession.
   int allocated_pooled_session_count_ = 0;
   std::deque<std::unique_ptr<PortAllocatorSession>> pooled_sessions_;
   bool prune_turn_ports_ = false;
 };
 
 }  // namespace cricket
 
 #endif  // WEBRTC_P2P_BASE_PORTALLOCATOR_H_