Unify documentation style in core HydroChrono headers and sources

Author: dav-og

include/hydroc/config/hydro_config.h

@@ -1,20 +1,11 @@
 /*********************************************************************
  * @file  hydro_config.h
- *
- * @brief Public configuration types for HydroChrono YAML configuration.
- *
- * This header defines the data structures used to represent parsed
- * hydro.yaml configuration files. Users and library consumers should
- * include this header to work with hydrodynamic configuration data.
+ * @brief Public configuration types for parsed YAML hydro settings.
  *
  * MAIN TYPES:
- * - HydroBody: Configuration for a single hydrodynamic body
- * - WaveSettings: Configuration for wave conditions
- * - YAMLHydroData: Top-level container for all configuration
- *
- * USAGE:
- * Include <hydroc/config/hydro_config.h> to access these types.
- * Use hydrochrono::hydro::LoadHydroConfigFromYaml() to parse YAML files.
+ *   - HydroBody: Per-body hydrodynamic settings (H5 file, flags)
+ *   - WaveSettings: Wave type, height, period, spectrum
+ *   - YAMLHydroData: Top-level container for hydro.yaml data
  *********************************************************************/
 
 #ifndef HYDROC_CONFIG_HYDRO_CONFIG_H

include/hydroc/core/force_component.h

@@ -1,6 +1,13 @@
 /*********************************************************************
  * @file  force_component.h
  * @brief Interface for hydrodynamic force components.
+ *
+ * MAIN TYPES:
+ *   - IHydroForceComponent: Abstract interface for force computation
+ *   - HydroComponentType: Enum for profiling (Hydrostatics/Radiation/Excitation)
+ *
+ * ROLE: All force components implement IHydroForceComponent. HydroSystem
+ * owns a collection of components and calls Compute() on each.
  *********************************************************************/
 
 #ifndef HYDROC_CORE_FORCE_COMPONENT_H

include/hydroc/core/hydro_system.h

@@ -1,6 +1,13 @@
 /*********************************************************************
  * @file  hydro_system.h
- * @brief HydroSystem façade: orchestrates force components to compute total forces.
+ * @brief HydroSystem: Chrono-free core that orchestrates force components.
+ *
+ * MAIN TYPES:
+ *   - HydroSystem: Owns force components, computes total BodyForces
+ *   - HydroSystemProfileStats: Timing/call counts per component type
+ *
+ * ROLE: This is the Chrono-free hydrodynamics core. HydroForces (façade)
+ * and ChronoHydroCoupler delegate force computation to HydroSystem.
  *********************************************************************/
 
 #ifndef HYDROC_CORE_HYDRO_SYSTEM_H

include/hydroc/core/hydro_types.h

@@ -1,6 +1,12 @@
 /*********************************************************************
  * @file  hydro_types.h
- * @brief Canonical type definitions for hydrodynamic force types.
+ * @brief Core type aliases for hydrodynamic forces.
+ *
+ * MAIN TYPES:
+ *   - GeneralizedForce: 6-DOF force vector for one body (Eigen::VectorXd)
+ *   - BodyForces: Vector of GeneralizedForce for all bodies
+ *
+ * ROLE: Canonical definitions used throughout the hydrodynamics core.
  *********************************************************************/
 
 #ifndef HYDROC_CORE_HYDRO_TYPES_H

include/hydroc/core/system_state.h

@@ -1,6 +1,13 @@
 /*********************************************************************
  * @file  system_state.h
- * @brief Common structs for body and system hydrodynamic state.
+ * @brief Chrono-free state structs for hydrodynamic computation.
+ *
+ * MAIN TYPES:
+ *   - BodyState: Position, orientation, velocities for one body
+ *   - SystemState: Vector of BodyState for all bodies
+ *
+ * ROLE: Input to HydroSystem and force components. Decouples core
+ * hydrodynamics from Chrono's ChBody representation.
  *********************************************************************/
 
 #ifndef HYDROC_CORE_SYSTEM_STATE_H

include/hydroc/coupling/chrono_coupler.h

@@ -1,6 +1,12 @@
 /*********************************************************************
  * @file  chrono_coupler.h
  * @brief ChronoHydroCoupler: bridges Chrono bodies and HydroSystem.
+ *
+ * MAIN TYPES:
+ *   - ChronoHydroCoupler: Adapter between Chrono and HydroSystem
+ *
+ * ROLE: Extracts SystemState from Chrono bodies, invokes HydroSystem
+ * to compute forces. Used internally by HydroForces façade.
  *********************************************************************/
 
 #ifndef HYDROC_COUPLING_CHRONO_COUPLER_H

include/hydroc/hydro_forces.h

@@ -1,48 +1,22 @@
-#ifndef HYDRO_FORCES_H
-#define HYDRO_FORCES_H
-
 /*********************************************************************
  * @file  hydro_forces.h
+ * @brief HydroForces façade: attaches hydrodynamic forces to Chrono bodies.
  *
- * @brief Header file of HydroForces main class and helper classes
- * ComponentFunc and ForceFunc6d.
- *
- * ARCHITECTURE:
- * HydroForces is a thin adapter over HydroSystem + ChronoHydroCoupler.
- * Force computation is handled internally by HydroSystem, which owns:
- *   - HydrostaticsComponent (restoring forces + buoyancy)
- *   - RadiationComponent (RIRF convolution, owns velocity history)
- *   - ExcitationComponent (wave forcing)
- *
- * The sign convention is: total = hydrostatics - radiation + waves.
- * (RadiationComponent applies the negative sign internally since damping
- * opposes motion.)
+ * MAIN TYPES:
+ *   - HydroForces: Primary hydrodynamics façade (adapter over HydroSystem)
+ *   - ForceFunc6d: Wraps 6-DOF force/torque callbacks per body
+ *   - ComponentFunc: Per-DOF force function for Chrono's ChForce system
  *
- * MAIN RESPONSIBILITIES:
- * - HydroForces: Façade over HydroSystem; provides Chrono force callbacks
- * - ForceFunc6d: Wraps 6-DOF force/torque callbacks for Chrono bodies
- * - ComponentFunc: Per-DOF force function for Chrono's ChForce system
+ * ROLE: This is the main entry point for C++ usage. Internally delegates
+ * to HydroSystem (Chrono-free core) and ChronoHydroCoupler. Used by both
+ * C++ tests/demos and the YAML runner (hydrochrono.exe).
  *
- * COMPONENT CONSTRUCTION:
- * Force components are constructed via factory methods:
- *   - CreateHydrostaticsComponent()
- *   - CreateRadiationComponent()
- *   - CreateExcitationComponent()
- * These are the single source of truth for component configuration.
- *
- * INTERACTIONS:
- * - Used by setup_hydro_from_yaml to create and configure HydroForces instances
- * - Called by Chrono during simulation via ChForce callbacks
- * - Reads HDF5 data through H5FileInfo (not directly exposed here)
- * - Uses WaveBase hierarchy for wave excitation (passed in constructor)
- *
- * KEY ASSUMPTIONS:
- * - Bodies are 1-indexed in CoordinateFuncForBody (legacy, from ForceFunc6d)
- * - All bodies share same H5 file (multibody data in single file)
- * - 6 DOF per body (surge, sway, heave, roll, pitch, yaw)
- * - Forces computed once per time step and cached via prev_time check
+ * KEY ASSUMPTIONS: 6 DOF per body, bodies named "body1", "body2", etc.
  *********************************************************************/
 
+#ifndef HYDRO_FORCES_H
+#define HYDRO_FORCES_H
+
 // Include hydro_types.h FIRST to ensure BodyForces and GeneralizedForce are available
 // before any other includes that might conflict (e.g., config/hydro_config.h)
 #include <hydroc/core/hydro_types.h>

include/hydroc/radiation/radiation_types.h

@@ -1,6 +1,10 @@
 /*********************************************************************
  * @file  radiation_types.h
  * @brief Public types for radiation damping configuration.
+ *
+ * MAIN TYPES:
+ *   - RadiationConvolutionMode: Baseline vs TaperedDirect RIRF processing
+ *   - TaperedDirectOptions: Smoothing, tapering, and export settings
  *********************************************************************/
 
 #ifndef HYDROC_RADIATION_TYPES_H

src/hydro/config/setup_from_yaml.cpp

@@ -1,35 +1,9 @@
 /*********************************************************************
  * @file  setup_from_yaml.cpp
+ * @brief Creates HydroForces from parsed YAML configuration.
  *
- * @brief Implementation of hydrodynamic setup from YAML data.
- *
- * OVERVIEW:
- * Implements the SetupHydroFromYAML function that connects YAML configuration
- * to Chrono bodies and creates a configured HydroForces instance. Handles body
- * matching, wave model creation, and convolution mode setup.
- *
- * MAIN RESPONSIBILITIES:
- * - Match bodies by name between YAML config and Chrono system
- * - Factory function for WaveBase implementations (RegularWave, IrregularWaves, NoWave)
- * - HydroForces initialization with matched bodies and H5 file path
- * - Configuration of radiation convolution options from YAML
- *
- * INTERACTIONS:
- * - Reads hydro_data (YAMLHydroData) from parser
- * - Accesses Chrono bodies from simulation system
- * - Creates WaveBase instances via factory pattern
- * - Configures HydroForces with convolution settings
- *
- * KEY ASSUMPTIONS:
- * - All bodies use same H5 file (takes first body's h5_file)
- * - Body names match exactly between YAML and Chrono
- * - Wave parameters are valid (height > 0 for regular waves, etc.)
- * - Simulation timestep/duration provided for irregular waves
- *
- * KNOWN LIMITATIONS:
- * - Single H5 file per system (no per-body files)
- * - Body matching fails silently if name not found (logs warning)
- * - No validation that matched body count matches H5 file structure
+ * Implements SetupHydroFromYAML(): matches YAML body configs to Chrono
+ * bodies, creates wave models, and returns a configured HydroForces.
  *********************************************************************/
 
 #include "setup_from_yaml.h"

src/hydro/config/setup_from_yaml.h

@@ -1,36 +1,9 @@
 /*********************************************************************
  * @file  setup_from_yaml.h
+ * @brief Factory function to create HydroForces from YAML configuration.
  *
- * @brief Setup hydrodynamic forces from parsed YAML data.
- *
- * OVERVIEW:
- * This file provides the main entry point for configuring hydrodynamic
- * forces from YAML configuration files. It bridges parsed configuration
- * data to the HydroForces force computation system.
- *
- * MAIN RESPONSIBILITIES:
- * - Match Chrono bodies with YAML body configurations by name
- * - Create appropriate WaveBase implementations from wave settings
- * - Initialize HydroForces with matched bodies and wave models
- * - Configure radiation convolution options (Baseline/TaperedDirect)
- *
- * INTERACTIONS:
- * - Takes parsed YAMLHydroData from yaml_parser
- * - Takes Chrono bodies from the simulation system
- * - Returns configured HydroForces instance ready for simulation
- * - Uses wave_types.h for wave model creation
- *
- * KEY ASSUMPTIONS:
- * - All bodies share the same H5 file (uses first body's h5_file)
- * - Body names in YAML match Chrono body names exactly
- * - Bodies are matched in order found in YAML (not sorted)
- * - Wave settings apply system-wide (not per-body)
- *
- * KNOWN LIMITATIONS:
- * - Single H5 file assumption (no per-body H5 files)
- * - No validation of body count vs H5 file contents
- * - Wave configuration is system-wide only
- * - Body matching is simple string equality (no fuzzy matching)
+ * Provides SetupHydroFromYAML() which matches YAML body configs to Chrono
+ * bodies, creates wave models, and returns a configured HydroForces.
  *********************************************************************/
 
 #ifndef HYDRO_CONFIG_SETUP_FROM_YAML_H