documentation updates, remove superfluous comments

tooling/pipeline/includes/biergarten_pipeline_orchestrator.h

@@ -2,11 +2,11 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
 
 /**
- * @file biergarten_data_generator.h
- * @brief Orchestration for end-to-end brewery data generation pipeline.
+ * @file biergarten_pipeline_orchestrator.h
+ * @brief Orchestration for end-to-end brewery and user data generation.
  *
- * Intent: Coordinates location loading, enrichment, and generation phases
- * to produce a complete dataset. Coordinates dependencies via composition root.
+ * Coordinates location loading, enrichment, and generation phases to produce
+ * a complete dataset, wiring dependencies selected at the composition root.
  */
 
 #include <memory>
@@ -20,16 +20,16 @@
 #include "services/logging/logger.h"
 
 /**
- * @brief Main data generator class for the Biergarten pipeline.
+ * @brief Main orchestrator for the Biergarten data generation pipeline.
  *
- * This class encapsulates the core logic for generating brewery data.
- * It handles location loading, city enrichment, and brewery generation.
+ * Handles location loading, city enrichment, and brewery/user generation.
  */
 class BiergartenPipelineOrchestrator {
  public:
   /**
    * @brief Constructs the orchestrator with injected pipeline dependencies.
    *
+   * @param logger Sink for pipeline diagnostics.
    * @param context_service Provides regional context for locations.
    * @param generator Implementation (Llama or Mock) for brewery/user
    * generation.
@@ -49,7 +49,7 @@ class BiergartenPipelineOrchestrator {
    * Performs the following steps:
    * 1. Load curated locations from JSON
    * 2. Resolve context for each city using the injected context service
-   * 3. Generate brewery data for sampled cities
+   * 3. Generate brewery and user data for sampled cities
    *
    * @note STRUCTURAL CONCURRENCY REQUIREMENT:
    * When transitioned to a multithreaded design, this method MUST
@@ -63,35 +63,27 @@ class BiergartenPipelineOrchestrator {
   bool Run();
 
  private:
-  /**
-   * @brief Logger instance for emitting pipeline messages.
-   */
   std::shared_ptr<ILogger> logger_;
-
-  /**
-   * @brief Owning context provider dependency.
-   */
   std::unique_ptr<IEnrichmentService> context_service_;
 
   /**
-   * @brief Generator dependency selected in the composition root.
+   * @brief Generator implementation selected at the composition root (Llama
+   * or Mock).
    */
   std::unique_ptr<DataGenerator> generator_;
 
   /**
-   * @brief Storage backend for generated brewery records.
+   * @brief Storage backend for generated brewery and user records.
    */
   std::unique_ptr<IExportService> exporter_;
 
-  /**
-   * @brief CLI configuration: paths, model settings, generation parameters.
-   */
   ApplicationOptions application_options_;
 
   /**
    * @brief Load locations from JSON and sample cities.
    *
-   * @return Vector of sampled locations capped at 50 entries.
+   * @return Vector of locations randomly sampled per
+   * PipelineOptions::location_count.
    */
   std::vector<Location> QueryCitiesWithCountries();
 
@@ -115,18 +107,11 @@ class BiergartenPipelineOrchestrator {
   void GenerateUsers(std::span<const EnrichedCity> cities);
 
   /**
-   * @brief Log the generated brewery results.
+   * @brief Log the generated brewery and user results.
    */
   void LogResults() const;
 
-  /**
-   * @brief Stores generated brewery data.
-   */
   std::vector<BreweryRecord> generated_breweries_;
-
-  /**
-   * @brief Stores generated user data.
-   */
   std::vector<UserRecord> generated_users_;
 };
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_