From 35a5c0785cad83615ff350b8926884bc2fd7b1d1 Mon Sep 17 00:00:00 2001 From: Aaron Po Date: Tue, 23 Jun 2026 01:04:46 -0400 Subject: [PATCH] documentation updates, remove superfluous comments --- .../biergarten_pipeline_orchestrator.h | 43 ++++++------------- .../includes/data_generation/json_grammars.h | 6 ++- .../data_generation/llama_generator.h | 5 --- tooling/pipeline/includes/data_model/models.h | 20 --------- .../pipeline/includes/llama_backend_state.h | 14 ------ .../services/database/export_service.h | 4 -- .../database/sqlite_statement_helpers.h | 2 + .../services/datetime/date_time_provider.h | 3 -- .../services/enrichment/enrichment_service.h | 3 -- .../services/enrichment/mock_enrichment.h | 13 ++++-- .../services/enrichment/wikipedia_service.h | 6 ++- .../pipeline/includes/web_client/web_client.h | 3 -- .../biergarten_pipeline_orchestrator.cc | 2 +- .../generate_breweries.cc | 2 +- .../generate_users.cc | 2 +- .../log_results.cc | 2 +- .../query_cities_with_countries.cc | 2 +- .../biergarten_pipeline_orchestrator/run.cc | 2 +- .../enrichment/wikipedia/fetch_extract.cc | 1 + .../enrichment/wikipedia/get_summary.cc | 2 +- .../enrichment/wikipedia/wikipedia_service.cc | 2 +- 21 files changed, 44 insertions(+), 95 deletions(-) diff --git a/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h b/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h index 61c6969..0011881 100644 --- a/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h +++ b/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 @@ -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 logger_; - - /** - * @brief Owning context provider dependency. - */ std::unique_ptr context_service_; /** - * @brief Generator dependency selected in the composition root. + * @brief Generator implementation selected at the composition root (Llama + * or Mock). */ std::unique_ptr generator_; /** - * @brief Storage backend for generated brewery records. + * @brief Storage backend for generated brewery and user records. */ std::unique_ptr 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 QueryCitiesWithCountries(); @@ -115,18 +107,11 @@ class BiergartenPipelineOrchestrator { void GenerateUsers(std::span 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 generated_breweries_; - - /** - * @brief Stores generated user data. - */ std::vector generated_users_; }; #endif // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_ diff --git a/tooling/pipeline/includes/data_generation/json_grammars.h b/tooling/pipeline/includes/data_generation/json_grammars.h index 40bd338..1c0fb1c 100644 --- a/tooling/pipeline/includes/data_generation/json_grammars.h +++ b/tooling/pipeline/includes/data_generation/json_grammars.h @@ -10,6 +10,9 @@ #include // 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 diff --git a/tooling/pipeline/includes/data_generation/llama_generator.h b/tooling/pipeline/includes/data_generation/llama_generator.h index a8e9159..8a43681 100644 --- a/tooling/pipeline/includes/data_generation/llama_generator.h +++ b/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; /** diff --git a/tooling/pipeline/includes/data_model/models.h b/tooling/pipeline/includes/data_model/models.h index 58989e1..6dcdb26 100644 --- a/tooling/pipeline/includes/data_model/models.h +++ b/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; /** diff --git a/tooling/pipeline/includes/llama_backend_state.h b/tooling/pipeline/includes/llama_backend_state.h index 78c1e57..d50fa80 100644 --- a/tooling/pipeline/includes/llama_backend_state.h +++ b/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; }; diff --git a/tooling/pipeline/includes/services/database/export_service.h b/tooling/pipeline/includes/services/database/export_service.h index 4fc414b..9f4d85c 100644 --- a/tooling/pipeline/includes/services/database/export_service.h +++ b/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; diff --git a/tooling/pipeline/includes/services/database/sqlite_statement_helpers.h b/tooling/pipeline/includes/services/database/sqlite_statement_helpers.h index 7523114..2025d41 100644 --- a/tooling/pipeline/includes/services/database/sqlite_statement_helpers.h +++ b/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; diff --git a/tooling/pipeline/includes/services/datetime/date_time_provider.h b/tooling/pipeline/includes/services/datetime/date_time_provider.h index 632f9af..a5f8ce5 100644 --- a/tooling/pipeline/includes/services/datetime/date_time_provider.h +++ b/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; diff --git a/tooling/pipeline/includes/services/enrichment/enrichment_service.h b/tooling/pipeline/includes/services/enrichment/enrichment_service.h index b2608e3..9c79137 100644 --- a/tooling/pipeline/includes/services/enrichment/enrichment_service.h +++ b/tooling/pipeline/includes/services/enrichment/enrichment_service.h @@ -15,9 +15,6 @@ */ class IEnrichmentService { public: - /** - * @brief Virtual destructor for polymorphic cleanup. - */ virtual ~IEnrichmentService() = default; /** diff --git a/tooling/pipeline/includes/services/enrichment/mock_enrichment.h b/tooling/pipeline/includes/services/enrichment/mock_enrichment.h index 0eae2ba..6d527eb 100644 --- a/tooling/pipeline/includes/services/enrichment/mock_enrichment.h +++ b/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 #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 { diff --git a/tooling/pipeline/includes/services/enrichment/wikipedia_service.h b/tooling/pipeline/includes/services/enrichment/wikipedia_service.h index b1bc5cf..6dc5c4b 100644 --- a/tooling/pipeline/includes/services/enrichment/wikipedia_service.h +++ b/tooling/pipeline/includes/services/enrichment/wikipedia_service.h @@ -36,7 +36,11 @@ class WikipediaEnrichmentService final : public IEnrichmentService { std::unique_ptr client_; std::shared_ptr 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 extract_cache_; }; diff --git a/tooling/pipeline/includes/web_client/web_client.h b/tooling/pipeline/includes/web_client/web_client.h index 33ae66f..a280b42 100644 --- a/tooling/pipeline/includes/web_client/web_client.h +++ b/tooling/pipeline/includes/web_client/web_client.h @@ -13,9 +13,6 @@ */ class WebClient { public: - /** - * @brief Virtual destructor for polymorphic cleanup. - */ virtual ~WebClient() = default; /** diff --git a/tooling/pipeline/src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc b/tooling/pipeline/src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc index 2c53d4e..9c0a0ea 100644 --- a/tooling/pipeline/src/biergarten_pipeline_orchestrator/biergarten_pipeline_orchestrator.cc +++ b/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" diff --git a/tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_breweries.cc b/tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_breweries.cc index 2e0eded..0ee023b 100644 --- a/tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_breweries.cc +++ b/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 diff --git a/tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_users.cc b/tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_users.cc index 2a8fb23..e72eb03 100644 --- a/tooling/pipeline/src/biergarten_pipeline_orchestrator/generate_users.cc +++ b/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 diff --git a/tooling/pipeline/src/biergarten_pipeline_orchestrator/log_results.cc b/tooling/pipeline/src/biergarten_pipeline_orchestrator/log_results.cc index b374f32..ca51601 100644 --- a/tooling/pipeline/src/biergarten_pipeline_orchestrator/log_results.cc +++ b/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 diff --git a/tooling/pipeline/src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc b/tooling/pipeline/src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc index d6e66c3..6fd850c 100644 --- a/tooling/pipeline/src/biergarten_pipeline_orchestrator/query_cities_with_countries.cc +++ b/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 diff --git a/tooling/pipeline/src/biergarten_pipeline_orchestrator/run.cc b/tooling/pipeline/src/biergarten_pipeline_orchestrator/run.cc index 3569a46..5ada0f6 100644 --- a/tooling/pipeline/src/biergarten_pipeline_orchestrator/run.cc +++ b/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 diff --git a/tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc b/tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc index 3bf3320..9bc5305 100644 --- a/tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc +++ b/tooling/pipeline/src/services/enrichment/wikipedia/fetch_extract.cc @@ -1,5 +1,6 @@ /** * @file wikipedia/fetch_extract.cc + * @brief WikipediaEnrichmentService::FetchExtract() implementation. */ #include diff --git a/tooling/pipeline/src/services/enrichment/wikipedia/get_summary.cc b/tooling/pipeline/src/services/enrichment/wikipedia/get_summary.cc index 6bb2558..342f84a 100644 --- a/tooling/pipeline/src/services/enrichment/wikipedia/get_summary.cc +++ b/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 diff --git a/tooling/pipeline/src/services/enrichment/wikipedia/wikipedia_service.cc b/tooling/pipeline/src/services/enrichment/wikipedia/wikipedia_service.cc index df32618..e5f3f54 100644 --- a/tooling/pipeline/src/services/enrichment/wikipedia/wikipedia_service.cc +++ b/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"