From 8d6b83673b85b430d65d15b07e603c3aadbac16a Mon Sep 17 00:00:00 2001 From: Aaron Po Date: Tue, 23 Jun 2026 00:45:32 -0400 Subject: [PATCH] Update doxygen comments --- .../biergarten_pipeline_orchestrator.h | 28 +++- .../includes/data_model/generated_models.h | 48 +++++-- tooling/pipeline/includes/data_model/models.h | 126 +++++++++++++----- .../includes/json_handling/json_loader.h | 12 +- .../pipeline/includes/llama_backend_state.h | 16 ++- .../services/database/export_service.h | 12 +- .../services/datetime/date_time_provider.h | 4 +- .../services/enrichment/enrichment_service.h | 4 +- .../services/enrichment/wikipedia_service.h | 16 ++- .../includes/services/logging/log_entry.h | 84 +++++++++--- .../pipeline/includes/web_client/web_client.h | 4 +- .../pipeline/src/json_handling/json_loader.cc | 8 +- 12 files changed, 269 insertions(+), 93 deletions(-) diff --git a/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h b/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h index f3f7c8d..61c6969 100644 --- a/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h +++ b/tooling/pipeline/includes/biergarten_pipeline_orchestrator.h @@ -63,19 +63,29 @@ class BiergartenPipelineOrchestrator { bool Run(); private: - /// @brief Logger instance for emitting pipeline messages. + /** + * @brief Logger instance for emitting pipeline messages. + */ std::shared_ptr logger_; - /// @brief Owning context provider dependency. + /** + * @brief Owning context provider dependency. + */ std::unique_ptr context_service_; - /// @brief Generator dependency selected in the composition root. + /** + * @brief Generator dependency selected in the composition root. + */ std::unique_ptr generator_; - /// @brief Storage backend for generated brewery records. + /** + * @brief Storage backend for generated brewery records. + */ std::unique_ptr exporter_; - /// @brief CLI configuration: paths, model settings, generation parameters. + /** + * @brief CLI configuration: paths, model settings, generation parameters. + */ ApplicationOptions application_options_; /** @@ -109,10 +119,14 @@ class BiergartenPipelineOrchestrator { */ void LogResults() const; - /// @brief Stores generated brewery data. + /** + * @brief Stores generated brewery data. + */ std::vector generated_breweries_; - /// @brief Stores generated user data. + /** + * @brief Stores generated user data. + */ std::vector generated_users_; }; #endif // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_ diff --git a/tooling/pipeline/includes/data_model/generated_models.h b/tooling/pipeline/includes/data_model/generated_models.h index aca59b2..ee9a8b9 100644 --- a/tooling/pipeline/includes/data_model/generated_models.h +++ b/tooling/pipeline/includes/data_model/generated_models.h @@ -19,16 +19,24 @@ * @brief Generated brewery payload. */ struct BreweryResult { - /// @brief Brewery display name in English. + /** + * @brief Brewery display name in English. + */ std::string name_en; - /// @brief Brewery description text in English. + /** + * @brief Brewery description text in English. + */ std::string description_en; - /// @brief Brewery display name in the local language. + /** + * @brief Brewery display name in the local language. + */ std::string name_local; - /// @brief Brewery description text in the local language. + /** + * @brief Brewery description text in the local language. + */ std::string description_local; }; @@ -36,26 +44,38 @@ struct BreweryResult { * @brief Generated user profile payload. */ struct UserResult { - /// @brief First (given) name, copied from the sampled Name -- not - /// LLM-invented. + /** + * @brief First (given) name, copied from the sampled Name -- not + * LLM-invented. + */ std::string first_name{}; - /// @brief Last (family) name, copied from the sampled Name -- not - /// LLM-invented. + /** + * @brief Last (family) name, copied from the sampled Name -- not + * LLM-invented. + */ std::string last_name{}; - /// @brief Gender associated with the sampled first name, copied from the - /// sampled Name -- not LLM-invented. + /** + * @brief Gender associated with the sampled first name, copied from the + * sampled Name -- not LLM-invented. + */ std::string gender{}; - /// @brief Username handle. + /** + * @brief Username handle. + */ std::string username{}; - /// @brief Short user biography. + /** + * @brief Short user biography. + */ std::string bio{}; - /// @brief Relative check-in/activity weight for this user, used to drive - /// a J-curve activity profile in later pipeline phases. + /** + * @brief Relative check-in/activity weight for this user, used to drive + * a J-curve activity profile in later pipeline phases. + */ float activity_weight{}; }; diff --git a/tooling/pipeline/includes/data_model/models.h b/tooling/pipeline/includes/data_model/models.h index 28ca9df..58989e1 100644 --- a/tooling/pipeline/includes/data_model/models.h +++ b/tooling/pipeline/includes/data_model/models.h @@ -28,28 +28,44 @@ namespace prog_opts = boost::program_options; * @brief Canonical location record for city-level generation. */ struct Location { - /// @brief City name. + /** + * @brief City name. + */ std::string city{}; - /// @brief State or province name. + /** + * @brief State or province name. + */ std::string state_province{}; - /// @brief ISO 3166-2 subdivision code. + /** + * @brief ISO 3166-2 subdivision code. + */ std::string iso3166_2{}; - /// @brief Country name. + /** + * @brief Country name. + */ std::string country{}; - /// @brief ISO 3166-1 country code. + /** + * @brief ISO 3166-1 country code. + */ std::string iso3166_1{}; - /// @brief Local language codes in priority order. + /** + * @brief Local language codes in priority order. + */ std::vector local_languages{}; - /// @brief Latitude in decimal degrees. + /** + * @brief Latitude in decimal degrees. + */ double latitude{}; - /// @brief Longitude in decimal degrees. + /** + * @brief Longitude in decimal degrees. + */ double longitude{}; }; @@ -63,14 +79,20 @@ struct Location { * Produced by NamesByCountry::SampleName(); */ struct Name { - /// @brief First (given) name. + /** + * @brief First (given) name. + */ std::string first_name{}; - /// @brief Last (family) name. + /** + * @brief Last (family) name. + */ std::string last_name{}; - /// @brief Gender associated with the sampled forename (e.g. "M", "F"), as - /// reported by the source dataset. + /** + * @brief Gender associated with the sampled forename (e.g. "M", "F"), as + * reported by the source dataset. + */ std::string gender{}; }; @@ -78,11 +100,15 @@ struct Name { * @brief A single forename entry from the names-by-country fixture data. */ struct ForenameEntry { - /// @brief Romanized forename. + /** + * @brief Romanized forename. + */ std::string name{}; - /// @brief Gender associated with this forename, as reported by the source - /// dataset (e.g. "M", "F"). + /** + * @brief Gender associated with this forename, as reported by the source + * dataset (e.g. "M", "F"). + */ std::string gender{}; }; @@ -90,13 +116,19 @@ struct ForenameEntry { * @brief A persona archetype used to ground LLM-generated user bios. */ struct UserPersona { - /// @brief Persona display name (e.g. "Hophead Explorer"). + /** + * @brief Persona display name (e.g. "Hophead Explorer"). + */ std::string name{}; - /// @brief Short description of the persona's interests and voice. + /** + * @brief Short description of the persona's interests and voice. + */ std::string description{}; - /// @brief Beer styles this persona gravitates toward. + /** + * @brief Beer styles this persona gravitates toward. + */ std::vector style_affinities{}; }; @@ -108,22 +140,34 @@ struct UserPersona { * @brief LLM sampling parameters. */ struct SamplingOptions { - /// @brief LLM sampling temperature (higher = more random). + /** + * @brief LLM sampling temperature (higher = more random). + */ float temperature = 1.0F; - /// @brief LLM nucleus sampling top-p parameter. + /** + * @brief LLM nucleus sampling top-p parameter. + */ float top_p = 0.95F; - /// @brief LLM top-k sampling parameter. + /** + * @brief LLM top-k sampling parameter. + */ uint32_t top_k = 64; - /// @brief Context window size (tokens). + /** + * @brief Context window size (tokens). + */ uint32_t n_ctx = 8192; - /// @brief Random seed (-1 for random, otherwise non-negative). + /** + * @brief Random seed (-1 for random, otherwise non-negative). + */ int seed = -1; - /// @brief Number of layers to offload to GPU. + /** + * @brief Number of layers to offload to GPU. + */ int n_gpu_layers = 0; }; @@ -131,14 +175,20 @@ struct SamplingOptions { * @brief Configuration for the LLM generator component. */ struct GeneratorOptions { - /// @brief Path to the LLM model file (gguf format). + /** + * @brief Path to the LLM model file (gguf format). + */ std::filesystem::path model_path; - /// @brief Use mocked generator instead of actual LLM inference. + /** + * @brief Use mocked generator instead of actual LLM inference. + */ bool use_mocked = false; - /// @brief Specific sampling parameters for this generator. - /// If nullopt, the application should use global defaults. + /** + * @brief Specific sampling parameters for this generator. + * If nullopt, the application should use global defaults. + */ std::optional sampling; }; @@ -146,18 +196,26 @@ struct GeneratorOptions { * @brief Configuration for the pipeline execution and output. */ struct PipelineOptions { - /// @brief Directory for generated artifacts. + /** + * @brief Directory for generated artifacts. + */ std::filesystem::path output_path; - /// @brief Directory that contains named prompt files (e.g. - /// BREWERY_GENERATION.md). + /** + * @brief Directory that contains named prompt files (e.g. + * BREWERY_GENERATION.md). + */ std::filesystem::path prompt_dir; - /// @brief Path for application logs. + /** + * @brief Path for application logs. + */ std::filesystem::path log_path; - /// @brief Number of locations to sample from the dataset - /// More locations -> more users/more breweries + /** + * @brief Number of locations to sample from the dataset + * More locations -> more users/more breweries + */ uint32_t location_count; }; diff --git a/tooling/pipeline/includes/json_handling/json_loader.h b/tooling/pipeline/includes/json_handling/json_loader.h index b8387c4..92236c6 100644 --- a/tooling/pipeline/includes/json_handling/json_loader.h +++ b/tooling/pipeline/includes/json_handling/json_loader.h @@ -14,14 +14,20 @@ #include "data_model/names_by_country.h" #include "services/logging/logger.h" -/// @brief Loads curated world locations from a JSON file into memory. +/** + * @brief Loads curated world locations from a JSON file into memory. + */ class JsonLoader { public: - /// @brief Parses a JSON array file and returns all location records. + /** + * @brief Parses a JSON array file and returns all location records. + */ static std::vector LoadLocations( const std::filesystem::path& filepath); - /// @brief Parses a JSON array file and returns all persona records. + /** + * @brief Parses a JSON array file and returns all persona records. + */ static std::vector LoadPersonas( const std::filesystem::path& filepath); diff --git a/tooling/pipeline/includes/llama_backend_state.h b/tooling/pipeline/includes/llama_backend_state.h index 09e9027..78c1e57 100644 --- a/tooling/pipeline/includes/llama_backend_state.h +++ b/tooling/pipeline/includes/llama_backend_state.h @@ -16,16 +16,24 @@ */ class LlamaBackendState { public: - /// @brief Initializes global llama backend state. + /** + * @brief Initializes global llama backend state. + */ LlamaBackendState() { llama_backend_init(); } - /// @brief Cleans up global llama backend state. + /** + * @brief Cleans up global llama backend state. + */ ~LlamaBackendState() { llama_backend_free(); } - /// @brief Non-copyable type. + /** + * @brief Non-copyable type. + */ LlamaBackendState(const LlamaBackendState&) = delete; - /// @brief Non-copyable type. + /** + * @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 3958b2f..4fc414b 100644 --- a/tooling/pipeline/includes/services/database/export_service.h +++ b/tooling/pipeline/includes/services/database/export_service.h @@ -17,7 +17,9 @@ class IExportService { public: IExportService() = default; - /// @brief Virtual destructor for polymorphic cleanup. + /** + * @brief Virtual destructor for polymorphic cleanup. + */ virtual ~IExportService() = default; IExportService(const IExportService&) = delete; @@ -25,7 +27,9 @@ class IExportService { IExportService(IExportService&&) = delete; IExportService& operator=(IExportService&&) = delete; - /// @brief Prepares the export destination for a new run. + /** + * @brief Prepares the export destination for a new run. + */ virtual void Initialize() = 0; /** @@ -42,7 +46,9 @@ class IExportService { */ virtual uint64_t ProcessRecord(const UserRecord& user) = 0; - /// @brief Finalizes the export destination. + /** + * @brief Finalizes the export destination. + */ virtual void Finalize() = 0; }; diff --git a/tooling/pipeline/includes/services/datetime/date_time_provider.h b/tooling/pipeline/includes/services/datetime/date_time_provider.h index 1c00dd1..632f9af 100644 --- a/tooling/pipeline/includes/services/datetime/date_time_provider.h +++ b/tooling/pipeline/includes/services/datetime/date_time_provider.h @@ -18,7 +18,9 @@ */ class IDateTimeProvider { public: - /// @brief Virtual destructor for polymorphic cleanup. + /** + * @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 32d02d6..b2608e3 100644 --- a/tooling/pipeline/includes/services/enrichment/enrichment_service.h +++ b/tooling/pipeline/includes/services/enrichment/enrichment_service.h @@ -15,7 +15,9 @@ */ class IEnrichmentService { public: - /// @brief Virtual destructor for polymorphic cleanup. + /** + * @brief Virtual destructor for polymorphic cleanup. + */ virtual ~IEnrichmentService() = default; /** diff --git a/tooling/pipeline/includes/services/enrichment/wikipedia_service.h b/tooling/pipeline/includes/services/enrichment/wikipedia_service.h index 82a97aa..b1bc5cf 100644 --- a/tooling/pipeline/includes/services/enrichment/wikipedia_service.h +++ b/tooling/pipeline/includes/services/enrichment/wikipedia_service.h @@ -15,21 +15,29 @@ #include "services/logging/logger.h" #include "web_client/web_client.h" -/// @brief Provides Wikipedia summary lookups backed by cached raw extracts. +/** + * @brief Provides Wikipedia summary lookups backed by cached raw extracts. + */ class WikipediaEnrichmentService final : public IEnrichmentService { public: - /// @brief Creates a new Wikipedia service with the provided web client. + /** + * @brief Creates a new Wikipedia service with the provided web client. + */ explicit WikipediaEnrichmentService(std::unique_ptr client, std::shared_ptr logger); - /// @brief Returns the Wikipedia-derived context for a location. + /** + * @brief Returns the Wikipedia-derived context for a location. + */ [[nodiscard]] std::string GetLocationContext(const Location& loc) override; private: std::string FetchExtract(std::string_view query); std::unique_ptr client_; std::shared_ptr logger_; - /// @brief Canonical cache for raw Wikipedia query extracts. + /** + * @brief Canonical cache for raw Wikipedia query extracts. + */ std::unordered_map extract_cache_; }; diff --git a/tooling/pipeline/includes/services/logging/log_entry.h b/tooling/pipeline/includes/services/logging/log_entry.h index 53f272e..b6d6fba 100644 --- a/tooling/pipeline/includes/services/logging/log_entry.h +++ b/tooling/pipeline/includes/services/logging/log_entry.h @@ -20,10 +20,22 @@ * @brief Severity levels supported by the logging infra. */ enum class LogLevel { - Debug, ///< Development/debugging information. - Info, ///< General informational messages. - Warn, ///< Warning conditions. - Error, ///< Error conditions. + /** + * @brief Development/debugging information. + */ + Debug, + /** + * @brief General informational messages. + */ + Info, + /** + * @brief Warning conditions. + */ + Warn, + /** + * @brief Error conditions. + */ + Error, }; /** @@ -34,14 +46,38 @@ enum class LogLevel { * pipeline that emitted it. */ enum class PipelinePhase { - Startup, ///< Initialization and validation. - Enrichment, ///< Location/context enrichment (e.g. Wikipedia lookups). - UserGeneration, ///< User profile generation. - BreweryAndBeerGeneration, ///< Brewery and beer data generation. - CheckinGeneration, ///< Checkin (visit) record generation. - RatingGeneration, ///< Rating and review generation. - FollowGeneration, ///< Follow relationship generation. - Teardown, ///< Finalization and cleanup. + /** + * @brief Initialization and validation. + */ + Startup, + /** + * @brief Location/context enrichment (e.g. Wikipedia lookups). + */ + Enrichment, + /** + * @brief User profile generation. + */ + UserGeneration, + /** + * @brief Brewery and beer data generation. + */ + BreweryAndBeerGeneration, + /** + * @brief Checkin (visit) record generation. + */ + CheckinGeneration, + /** + * @brief Rating and review generation. + */ + RatingGeneration, + /** + * @brief Follow relationship generation. + */ + FollowGeneration, + /** + * @brief Finalization and cleanup. + */ + Teardown, }; /** @@ -66,22 +102,34 @@ struct LogDTO { * before the entry is dispatched. */ struct LogEntry { - /// @brief Timestamp when the entry was created. + /** + * @brief Timestamp when the entry was created. + */ std::chrono::system_clock::time_point timestamp{}; - /// @brief Source location where the log call was made. + /** + * @brief Source location where the log call was made. + */ std::source_location origin{}; - /// @brief Thread responsible for emitting the log. + /** + * @brief Thread responsible for emitting the log. + */ std::thread::id thread_id{}; - /// @brief Severity level of this entry. + /** + * @brief Severity level of this entry. + */ LogLevel level; - /// @brief Pipeline phase associated with the entry. + /** + * @brief Pipeline phase associated with the entry. + */ PipelinePhase phase; - /// @brief Log message text. + /** + * @brief Log message text. + */ std::string message; }; diff --git a/tooling/pipeline/includes/web_client/web_client.h b/tooling/pipeline/includes/web_client/web_client.h index 641eb12..33ae66f 100644 --- a/tooling/pipeline/includes/web_client/web_client.h +++ b/tooling/pipeline/includes/web_client/web_client.h @@ -13,7 +13,9 @@ */ class WebClient { public: - /// @brief Virtual destructor for polymorphic cleanup. + /** + * @brief Virtual destructor for polymorphic cleanup. + */ virtual ~WebClient() = default; /** diff --git a/tooling/pipeline/src/json_handling/json_loader.cc b/tooling/pipeline/src/json_handling/json_loader.cc index 15b4558..d279b57 100644 --- a/tooling/pipeline/src/json_handling/json_loader.cc +++ b/tooling/pipeline/src/json_handling/json_loader.cc @@ -83,9 +83,11 @@ boost::json::value ParseJsonFile(const std::filesystem::path& filepath, return root; } -/// @brief Returns the first element of a string array field, falling back to -/// `fallback_key` if `key` is missing/empty (some source entries only have a -/// "localized" form and no "romanized" form). +/** + * @brief Returns the first element of a string array field, falling back to + * `fallback_key` if `key` is missing/empty (some source entries only have a + * "localized" form and no "romanized" form). + */ std::string ReadFirstOfStringArray(const boost::json::object& object, const char* key, const char* fallback_key) { for (const char* candidate_key : {key, fallback_key}) {