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
+ * @file biergarten_pipeline_orchestrator.h
- * @brief Orchestration for end-to-end brewery data generation pipeline.
+ * @brief Orchestration for end-to-end brewery and user data generation.
  *
- * Intent: Coordinates location loading, enrichment, and generation phases
+ * Coordinates location loading, enrichment, and generation phases to produce
- * to produce a complete dataset. Coordinates dependencies via composition root.
+ * 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.
+ * Handles location loading, city enrichment, and brewery/user generation.
- * It handles location loading, city enrichment, and brewery 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_

tooling/pipeline/includes/data_generation/json_grammars.h

@@ -10,6 +10,9 @@
 #include <string_view>
 
 // GBNF grammar for structured user JSON output.
+// thought-block permits the model to emit free-form reasoning before the
+// JSON object (the prompts explicitly invite this); only the "{...}" tail is
+// constrained to the expected shape.
 inline constexpr std::string_view kUserJsonGrammar = R"json_user(
 root ::= thought-block "{" ws
     "\"username\"" ws ":" ws string ws "," ws
@@ -25,7 +28,8 @@ hex           ::= [0-9a-fA-F]
 number        ::= "-"? ("0" | [1-9] [0-9]*) ("." [0-9]+)?
 )json_user";
 
-// GBNF grammar for structured brewery JSON output.
+// GBNF grammar for structured brewery JSON output (see thought-block note
+// above).
 inline constexpr std::string_view kBreweryJsonGrammar = R"json_brewery(
 root ::= thought-block "{" ws
     "\"name_en\"" ws ":" ws string ws "," ws

tooling/pipeline/includes/data_generation/llama_generator.h

@@ -44,14 +44,9 @@ class LlamaGenerator final : public DataGenerator {
 
   ~LlamaGenerator() override;
 
-  // disable copy constructor
   LlamaGenerator(const LlamaGenerator&) = delete;
-
-  // disable copy assignment operator
   LlamaGenerator& operator=(const LlamaGenerator&) = delete;
-  // disable move constructor
   LlamaGenerator(LlamaGenerator&&) = delete;
-  // disable move assignment operator
   LlamaGenerator& operator=(LlamaGenerator&&) = delete;
 
   /**

tooling/pipeline/includes/data_model/models.h

@@ -28,14 +28,7 @@ namespace prog_opts = boost::program_options;
  * @brief Canonical location record for city-level generation.
  */
 struct Location {
-  /**
-   * @brief City name.
-   */
   std::string city{};
-
-  /**
-   * @brief State or province name.
-   */
   std::string state_province{};
 
   /**
@@ -43,9 +36,6 @@ struct Location {
    */
   std::string iso3166_2{};
 
-  /**
-   * @brief Country name.
-   */
   std::string country{};
 
   /**
@@ -79,14 +69,7 @@ struct Location {
  * Produced by NamesByCountry::SampleName();
  */
 struct Name {
-  /**
-   * @brief First (given) name.
-   */
   std::string first_name{};
-
-  /**
-   * @brief Last (family) name.
-   */
   std::string last_name{};
 
   /**
@@ -207,9 +190,6 @@ struct PipelineOptions {
    */
   std::filesystem::path prompt_dir;
 
-  /**
-   * @brief Path for application logs.
-   */
   std::filesystem::path log_path;
 
   /**

tooling/pipeline/includes/llama_backend_state.h

@@ -16,24 +16,10 @@
  */
 class LlamaBackendState {
  public:
-  /**
-   * @brief Initializes global llama backend state.
-   */
   LlamaBackendState() { llama_backend_init(); }
-
-  /**
-   * @brief Cleans up global llama backend state.
-   */
   ~LlamaBackendState() { llama_backend_free(); }
 
-  /**
-   * @brief Non-copyable type.
-   */
   LlamaBackendState(const LlamaBackendState&) = delete;
-
-  /**
-   * @brief Non-copyable type.
-   */
   LlamaBackendState& operator=(const LlamaBackendState&) = delete;
 };
 

tooling/pipeline/includes/services/database/export_service.h

@@ -16,10 +16,6 @@
 class IExportService {
  public:
   IExportService() = default;
-
-  /**
-   * @brief Virtual destructor for polymorphic cleanup.
-   */
   virtual ~IExportService() = default;
 
   IExportService(const IExportService&) = delete;

tooling/pipeline/includes/services/database/sqlite_statement_helpers.h

@@ -109,6 +109,8 @@ INSERT INTO users (
 ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?);
 )sql";
 
+// sqlite3_bind_*() parameter indices are 1-based, matching the "?"
+// placeholder order in the SQL above.
 inline constexpr int kLocationCityBindIndex = 1;
 inline constexpr int kLocationStateProvinceBindIndex = 2;
 inline constexpr int kLocationIso31662BindIndex = 3;

tooling/pipeline/includes/services/datetime/date_time_provider.h

@@ -18,9 +18,6 @@
  */
 class IDateTimeProvider {
  public:
-  /**
-   * @brief Virtual destructor for polymorphic cleanup.
-   */
   virtual ~IDateTimeProvider() = default;
 
   IDateTimeProvider() = default;

tooling/pipeline/includes/services/enrichment/enrichment_service.h

@@ -15,9 +15,6 @@
  */
 class IEnrichmentService {
  public:
-  /**
-   * @brief Virtual destructor for polymorphic cleanup.
-   */
   virtual ~IEnrichmentService() = default;
 
   /**

tooling/pipeline/includes/services/enrichment/mock_enrichment.h

@@ -1,13 +1,18 @@
-//
-// Created by aaronpo on 13/05/2026.
-//
-
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_MOCK_ENRICHMENT_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_MOCK_ENRICHMENT_H_
+
+/**
+ * @file services/enrichment/mock_enrichment.h
+ * @brief No-op IEnrichmentService used when network enrichment is disabled.
+ */
+
 #include <string>
 
 #include "enrichment_service.h"
 
+/**
+ * @brief Enrichment service that returns no context for any location.
+ */
 class MockEnrichmentService final : public IEnrichmentService {
  public:
   std::string GetLocationContext(const Location& /*loc*/) override {

tooling/pipeline/includes/services/enrichment/wikipedia_service.h

@@ -36,7 +36,11 @@ class WikipediaEnrichmentService final : public IEnrichmentService {
   std::unique_ptr<WebClient> client_;
   std::shared_ptr<ILogger> logger_;
   /**
-   * @brief Canonical cache for raw Wikipedia query extracts.
+   * @brief Cache for raw Wikipedia query extracts, keyed by query string.
+   *
+   * GetLocationContext() always queries "brewing" and reuses "beer in
+   * {country}" for every city in that country, so caching avoids refetching
+   * the same extract across locations in a run.
    */
   std::unordered_map<std::string, std::string> extract_cache_;
 };

tooling/pipeline/includes/web_client/web_client.h

@@ -13,9 +13,6 @@
  */
 class WebClient {
  public:
-  /**
-   * @brief Virtual destructor for polymorphic cleanup.
-   */
   virtual ~WebClient() = default;
 
   /**

tooling/pipeline/src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc
- * @brief BiergartenDataGenerator constructor implementation.
+ * @brief BiergartenPipelineOrchestrator constructor implementation.
  */
 
 #include "biergarten_pipeline_orchestrator.h"

tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_breweries.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/generate_breweries.cc
- * @brief BiergartenDataGenerator::GenerateBreweries() implementation.
+ * @brief BiergartenPipelineOrchestrator::GenerateBreweries() implementation.
  */
 
 #include <chrono>

tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_users.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/generate_users.cc
- * @brief BiergartenDataGenerator::GenerateUsers() implementation.
+ * @brief BiergartenPipelineOrchestrator::GenerateUsers() implementation.
  */
 
 #include <cctype>

tooling/pipeline/src/biergarten_pipeline_orchestrator/log_results.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/log_results.cc
- * @brief BiergartenDataGenerator::LogResults() implementation.
+ * @brief BiergartenPipelineOrchestrator::LogResults() implementation.
  */
 
 #include <boost/json/array.hpp>

tooling/pipeline/src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/query_cities_with_countries.cc
- * @brief BiergartenDataGenerator::QueryCitiesWithCountries() implementation.
+ * @brief BiergartenPipelineOrchestrator::QueryCitiesWithCountries() implementation.
  */
 
 #include <algorithm>

tooling/pipeline/src/biergarten_pipeline_orchestrator/run.cc

@@ -1,6 +1,6 @@
 /**
  * @file biergarten_pipeline_orchestrator/run.cc
- * @brief BiergartenDataGenerator::Run() implementation.
+ * @brief BiergartenPipelineOrchestrator::Run() implementation.
  */
 
 #include <chrono>

tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc

@@ -1,5 +1,6 @@
 /**
  * @file wikipedia/fetch_extract.cc
+ * @brief WikipediaEnrichmentService::FetchExtract() implementation.
  */
 
 #include <boost/json.hpp>

tooling/pipeline/src/services/enrichment/wikipedia/get_summary.cc

@@ -1,6 +1,6 @@
 /**
  * @file wikipedia/get_summary.cc
- * @brief WikipediaService::GetLocationContext() implementation.
+ * @brief WikipediaEnrichmentService::GetLocationContext() implementation.
  */
 
 #include <chrono>

tooling/pipeline/src/services/enrichment/wikipedia/wikipedia_service.cc

@@ -1,6 +1,6 @@
 /**
  * @file services/wikipedia/wikipedia_service.cc
- * @brief WikipediaService constructor implementation.
+ * @brief WikipediaEnrichmentService constructor implementation.
  */
 
 #include "services/enrichment/wikipedia_service.h"