Update doxygen comments

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<ILogger> logger_;
 
-  /// @brief Owning context provider dependency.
+  /**
+   * @brief Owning context provider dependency.
+   */
   std::unique_ptr<IEnrichmentService> context_service_;
 
-  /// @brief Generator dependency selected in the composition root.
+  /**
+   * @brief Generator dependency selected in the composition root.
+   */
   std::unique_ptr<DataGenerator> generator_;
 
-  /// @brief Storage backend for generated brewery records.
+  /**
+   * @brief Storage backend for generated brewery records.
+   */
   std::unique_ptr<IExportService> 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<BreweryRecord> generated_breweries_;
 
-  /// @brief Stores generated user data.
+  /**
+   * @brief Stores generated user data.
+   */
   std::vector<UserRecord> generated_users_;
 };
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_

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{};
 };
 

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<std::string> 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<std::string> 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<SamplingOptions> 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;
 };
 

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<Location> 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<UserPersona> LoadPersonas(
       const std::filesystem::path& filepath);
 

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;
 };
 

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;
 };
 

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;

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;
 
   /**

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<WebClient> client,
                                       std::shared_ptr<ILogger> 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<WebClient> client_;
   std::shared_ptr<ILogger> logger_;
-  /// @brief Canonical cache for raw Wikipedia query extracts.
+  /**
+   * @brief Canonical cache for raw Wikipedia query extracts.
+   */
   std::unordered_map<std::string, std::string> extract_cache_;
 };
 

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.
+   * @brief Development/debugging information.
-  Warn,   ///< Warning conditions.
+   */
-  Error,  ///< Error conditions.
+  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).
+   * @brief Initialization and validation.
-  UserGeneration,  ///< User profile generation.
+   */
-  BreweryAndBeerGeneration,  ///< Brewery and beer data generation.
+  Startup,
-  CheckinGeneration,         ///< Checkin (visit) record generation.
+  /**
-  RatingGeneration,          ///< Rating and review generation.
+   * @brief Location/context enrichment (e.g. Wikipedia lookups).
-  FollowGeneration,          ///< Follow relationship generation.
+   */
-  Teardown,                  ///< Finalization and cleanup.
+  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;
 };
 

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;
 
   /**

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
+ * @brief Returns the first element of a string array field, falling back to
-/// "localized" form and no "romanized" form).
+ * `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}) {