Add doc comment to Pipeline

Adds more detailed documentation to the Pipeline class. Also fixes a
typo in fml::Semaphore docs.

Author: cbracken

fml/synchronization/semaphore.h

@@ -67,7 +67,7 @@ class Semaphore {
   ///             Which makes doing the validity check before this call doubly
   ///             important.
   ///
-  /// @return     If the count could be decrement.
+  /// @return     If the count could be decremented.
   ///
   [[nodiscard]] bool TryWait();
 

shell/common/pipeline.h

@@ -36,6 +36,20 @@ size_t GetNextPipelineTraceID();
 
 /// A thread-safe queue of resources for a single consumer and a single
 /// producer.
+///
+/// Pipelines support two key operations: produce and consume.
+///
+/// The consumer calls `Consume` to wait for a resource to be produced and
+/// consume it when ready.
+///
+/// The producer calls `Produce` to generate a `ProducerContinuation` which
+/// provides a means to enqueue a resource in the pipeline. When the resource
+/// has been prepared, the producer calls `Complete` on the continuation, which
+/// enqueues the resource and signals the waiting consumer.
+///
+/// Pipelines generate the following tracing information:
+/// * PipelineProduce: async flow tracking time taken to produce a resource.
+/// * Pipeline Depth: counter of inflight resource producers.
 template <class R>
 class Pipeline {
  public:
@@ -70,6 +84,7 @@ class Pipeline {
       }
     }
 
+    /// Completes the continuation with the specified resource.
     [[nodiscard]] PipelineProduceResult Complete(ResourcePtr resource) {
       PipelineProduceResult result;
       if (continuation_) {
@@ -108,6 +123,8 @@ class Pipeline {
 
   bool IsValid() const { return empty_.IsValid() && available_.IsValid(); }
 
+  // Creates a `ProducerContinuation` that a producer can use to add a resource
+  // to the queue.
   ProducerContinuation Produce() {
     if (!empty_.TryWait()) {
       return {};
@@ -124,8 +141,9 @@ class Pipeline {
         GetNextPipelineTraceID()};         // trace id
   }
 
-  // Create a `ProducerContinuation` that will only push the task if the queue
+  // Creates a `ProducerContinuation` that will only push the task if the queue
   // is empty.
+  //
   // Prefer using |Produce|. ProducerContinuation returned by this method
   // doesn't guarantee that the frame will be rendered.
   ProducerContinuation ProduceIfEmpty() {
@@ -186,6 +204,7 @@ class Pipeline {
   std::mutex queue_mutex_;
   std::deque<std::pair<ResourcePtr, size_t>> queue_;
 
+  /// Commits a produced resource to the queue and signals the consumer.
   PipelineProduceResult ProducerCommit(ResourcePtr resource, size_t trace_id) {
     bool is_first_item = false;
     {