Document Enviroment is preferred as 1st parameter
No-Try: true
Bug: webrtc:15656
Change-Id: I82a642b8a558bad8c3264ab830ff07aea3584c98
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/329022
Reviewed-by: Harald Alvestrand <hta@webrtc.org>
Commit-Queue: Danil Chapovalov <danilchap@webrtc.org>
Cr-Commit-Position: refs/heads/main@{#41258}
diff --git a/api/environment/environment.h b/api/environment/environment.h
index 0849b0a..d86b7ae 100644
--- a/api/environment/environment.h
+++ b/api/environment/environment.h
@@ -40,12 +40,18 @@
// passed as a construction parameter and saved by value in each class that
// needs it. Most classes shouldn't create a new instance of the `Environment`,
// but instead should use a propagated copy.
+// Usually Environment should be the first parameter in a constructor or a
+// factory, and the first member in the class. Keeping Environment as the first
+// member in the class ensures utilities (e.g. clock) are still valid during
+// destruction of other members.
+//
// Example:
// class PeerConnection {
// public:
// PeerConnection(const Environment& env, ...)
// : env_(env),
-// rtp_manager_(env, ...),
+// log_duration_on_destruction_(&env_.clock()),
+// rtp_manager_(env_, ...),
// ...
//
// const FieldTrialsView& trials() const { return env_.field_trials(); }
@@ -56,6 +62,7 @@
//
// private:
// const Environment env_;
+// Stats log_duration_on_destruction_;
// RtpTransmissionManager rtp_manager_;
// };
// This class is thread safe.
