Supplement doc comments in interface headers.

include/nighthawk/client/factories.h

@@ -24,19 +24,44 @@ namespace Client {
 class BenchmarkClientFactory {
 public:
   virtual ~BenchmarkClientFactory() = default;
+
+  /**
+   * Constructs a BenchmarkClient
+   *
+   * @param api reference to the Api object.
+   * @param dispatcher supplies the owning thread's dispatcher.
+   * @param scope stats scope for any stats tracked by the benchmark client.
+   * @param cluster_manager Cluster manager preconfigured with our target cluster.
+   * @param http_tracer Shared pointer to an http tracer implementation (e.g. Zipkin).
+   * @param cluster_name Name of the cluster that this benchmark client will use. In conjunction
+   * with cluster_manager this will allow the this BenchmarkClient to access the target connection
+   * pool.
+   * @param request_source Source of request-specifiers. Will be queries every time the
+   * BenchmarkClient is asked to issue a request.
+   *
+   * @return BenchmarkClientPtr pointer to a BenchmarkClient instance.
+   */
   virtual BenchmarkClientPtr create(Envoy::Api::Api& api, Envoy::Event::Dispatcher& dispatcher,
                                     Envoy::Stats::Scope& scope,
                                     Envoy::Upstream::ClusterManagerPtr& cluster_manager,
                                     Envoy::Tracing::HttpTracerSharedPtr& http_tracer,
                                     absl::string_view cluster_name,
-                                    RequestSource& request_generator) const PURE;
+                                    RequestSource& request_source) const PURE;
 };
 
 class OutputFormatterFactory {
 public:
   virtual ~OutputFormatterFactory() = default;
+
+  /**
+   * Constructs an OutputFormatter instance according to the requested output format.
+   *
+   * @param options Proto configuration object indicating the desired output format.
+   *
+   * @return OutputFormatterPtr pointer to an OutputFormatter instance.
+   */
   virtual OutputFormatterPtr
-  create(const nighthawk::client::OutputFormat_OutputFormatOptions) const PURE;
+  create(const nighthawk::client::OutputFormat_OutputFormatOptions options) const PURE;
 };
 
 } // namespace Client

include/nighthawk/client/output_collector.h

@@ -15,6 +15,15 @@ namespace Client {
 class OutputCollector {
 public:
   virtual ~OutputCollector() = default;
+
+  /**
+   * Adds a result to the structured output.
+   *
+   * @param name unique name of the result. E.g. worker_1.
+   * @param statistics Reference to a vector of statistics to add to the output.
+   * @param counters Reference to a map of counter values, keyed by name, to add to the output.
+   * @param execution_duration Execution duration associated to the to-be-added result.
+   */
   virtual void addResult(absl::string_view name, const std::vector<StatisticPtr>& statistics,
                          const std::map<std::string, uint64_t>& counters,
                          const std::chrono::nanoseconds execution_duration) PURE;
@@ -24,6 +33,10 @@ class OutputCollector {
    * @param output the output value to set.
    */
   virtual void setOutput(const nighthawk::client::Output& output) PURE;
+
+  /**
+   * @return nighthawk::client::Output proto output object.
+   */
   virtual nighthawk::client::Output toProto() const PURE;
 };
 

include/nighthawk/client/output_formatter.h

@@ -17,6 +17,11 @@ namespace Client {
 class OutputFormatter {
 public:
   virtual ~OutputFormatter() = default;
+
+  /**
+   * @return std::string serialized representation of output. The specific format depends
+   * on the derived class, for example human-readable or json.
+   */
   virtual std::string formatProto(const nighthawk::client::Output& output) const PURE;
 };
 

include/nighthawk/common/request.h

@@ -15,6 +15,10 @@ using HeaderMapPtr = std::shared_ptr<const Envoy::Http::RequestHeaderMap>;
 class Request {
 public:
   virtual ~Request() = default;
+
+  /**
+   * @return HeaderMapPtr shared pointer to a request header specification.
+   */
   virtual HeaderMapPtr header() const PURE;
   // TODO(oschaaf): expectations
 };