GEAR: Fix documentation

doc/Doxyfile.in

@@ -770,12 +770,18 @@ INPUT		       += @top_srcdir@/src/cooling/const_du
 INPUT		       += @top_srcdir@/src/cooling/const_lambda
 INPUT		       += @top_srcdir@/src/cooling/Compton
 INPUT		       += @top_srcdir@/src/cooling/EAGLE
+INPUT		       += @top_srcdir@/src/cooling/grackle
 INPUT		       += @top_srcdir@/src/chemistry/EAGLE
+INPUT		       += @top_srcdir@/src/chemistry/GEAR
 INPUT		       += @top_srcdir@/src/entropy_floor/EAGLE
+INPUT		       += @top_srcdir@/src/pressure_floor/GEAR
 INPUT		       += @top_srcdir@/src/star_formation/EAGLE
+INPUT		       += @top_srcdir@/src/star_formation/GEAR
 INPUT		       += @top_srcdir@/src/tracers/EAGLE
 INPUT		       += @top_srcdir@/src/stars/EAGLE
+INPUT		       += @top_srcdir@/src/stars/GEAR
 INPUT		       += @top_srcdir@/src/feedback/EAGLE
+INPUT		       += @top_srcdir@/src/feedback/GEAR
 INPUT		       += @top_srcdir@/src/black_holes/EAGLE
 INPUT		       += @top_srcdir@/logger
 

src/chemistry/GEAR/chemistry.h

@@ -272,11 +272,12 @@ __attribute__((always_inline)) INLINE static float chemistry_timestep(
  * @brief Sets the chemistry properties of the (x-)particles to a valid start
  * state.
  *
- * Nothing to do here.
- *
+ * @param phys_const The #phys_const.
+ * @param us The #unit_system.
+ * @param cosmo The #cosmology.
+ * @param data The global chemistry information.
  * @param p Pointer to the particle data.
  * @param xp Pointer to the extended particle data.
- * @param data The global chemistry information.
  */
 __attribute__((always_inline)) INLINE static void chemistry_first_init_part(
     const struct phys_const* restrict phys_const,

src/cooling/grackle/cooling.c

@@ -143,9 +143,13 @@ int cooling_converged(const struct xpart* restrict xp,
 /**
  * @brief Compute equilibrium fraction
  *
+ * @param phys_const The #phys_const.
+ * @param us The #unit_system.
+ * @param hydro_properties The #hydro_props.
+ * @param cosmo The #cosmology
+ * @param cooling The properties of the cooling function.
  * @param p Pointer to the particle data.
  * @param xp Pointer to the extended particle data.
- * @param cooling The properties of the cooling function.
  */
 void cooling_compute_equilibrium(
     const struct phys_const* restrict phys_const,
@@ -198,9 +202,13 @@ void cooling_compute_equilibrium(
  * @brief Sets the cooling properties of the (x-)particles to a valid start
  * state.
  *
+ * @param phys_const The #phys_const.
+ * @param us The #unit_system.
+ * @param hydro_props The #hydro_props.
+ * @param cosmo The #cosmology.
+ * @param cooling The properties of the cooling function.
  * @param p Pointer to the particle data.
  * @param xp Pointer to the extended particle data.
- * @param cooling The properties of the cooling function.
  */
 void cooling_first_init_part(const struct phys_const* restrict phys_const,
                              const struct unit_system* restrict us,
@@ -292,7 +300,7 @@ void cooling_print_backend(const struct cooling_function_data* cooling) {
 /**
  * @brief copy a #xpart to the grackle data
  *
- * @param data The #grackle_field_data
+ * @param data The grackle_field_data structure from grackle.
  * @param p The #part
  * @param xp The #xpart
  * @param rho Particle density
@@ -338,7 +346,7 @@ void cooling_copy_to_grackle1(grackle_field_data* data, const struct part* p,
 /**
  * @brief copy a #xpart to the grackle data
  *
- * @param data The #grackle_field_data
+ * @param data The grackle_field_data structure from grackle.
  * @param p The #part
  * @param xp The #xpart
  * @param rho Particle density
@@ -370,7 +378,7 @@ void cooling_copy_to_grackle2(grackle_field_data* data, const struct part* p,
 /**
  * @brief copy a #xpart to the grackle data
  *
- * @param data The #grackle_field_data
+ * @param data The grackle_field_data structure from grackle.
  * @param p The #part
  * @param xp The #xpart
  * @param rho Particle density
@@ -402,10 +410,10 @@ void cooling_copy_to_grackle3(grackle_field_data* data, const struct part* p,
 /**
  * @brief copy the grackle data to a #xpart
  *
- * @param data The #grackle_field_data
- * @param p The #part
- * @param xp The #xpart
- * @param rho Particle density
+ * @param data The grackle_field_data structure from grackle.
+ * @param p The #part.
+ * @param xp The #xpart.
+ * @param rho The particle density.
  */
 #if COOLING_GRACKLE_MODE > 0
 void cooling_copy_from_grackle1(grackle_field_data* data, const struct part* p,
@@ -435,12 +443,12 @@ void cooling_copy_from_grackle1(grackle_field_data* data, const struct part* p,
 #endif
 
 /**
- * @brief copy the grackle data to a #xpart
+ * @brief copy the grackle data to a #xpart.
  *
- * @param data The #grackle_field_data
- * @param p The #part
- * @param xp The #xpart
- * @param rho Particle density
+ * @param data The grackle_field_data structure from grackle.
+ * @param p The #part.
+ * @param xp The #xpart.
+ * @param rho The particle density.
  */
 #if COOLING_GRACKLE_MODE > 1
 void cooling_copy_from_grackle2(grackle_field_data* data, const struct part* p,
@@ -460,10 +468,10 @@ void cooling_copy_from_grackle2(grackle_field_data* data, const struct part* p,
 /**
  * @brief copy the grackle data to a #xpart
  *
- * @param data The #grackle_field_data
- * @param p The #part
- * @param xp The #xpart
- * @param rho Particle density
+ * @param data The grackle_field_data structure from grackle.
+ * @param p The #part.
+ * @param xp The #xpart.
+ * @param rho The particle density.
  */
 #if COOLING_GRACKLE_MODE > 2
 void cooling_copy_from_grackle3(grackle_field_data* data, const struct part* p,
@@ -489,10 +497,10 @@ void cooling_copy_from_grackle3(grackle_field_data* data, const struct part* p,
  * Warning this function creates some variable, therefore the grackle call
  * should be in a block that still has the variables.
  *
- * @param data The #grackle_field_data
- * @param p The #part
- * @param xp The #xpart
- * @param rho Particle density
+ * @param data The grackle_field_data structure from grackle.
+ * @param p The #part.
+ * @param xp The #xpart.
+ * @param rho The particle density.
  */
 void cooling_copy_to_grackle(grackle_field_data* data, const struct part* p,
                              struct xpart* xp, gr_float rho) {
@@ -520,10 +528,10 @@ void cooling_copy_to_grackle(grackle_field_data* data, const struct part* p,
  * Warning this function creates some variable, therefore the grackle call
  * should be in a block that still has the variables.
  *
- * @param data The #grackle_field_data
- * @param p The #part
- * @param xp The #xpart
- * @param rho Particle density
+ * @param data The grackle_field_data structure from grackle.
+ * @param p The #part.
+ * @param xp The #xpart.
+ * @param rho The particle density.
  */
 void cooling_copy_from_grackle(grackle_field_data* data, const struct part* p,
                                struct xpart* xp, gr_float rho) {
@@ -539,9 +547,9 @@ void cooling_copy_from_grackle(grackle_field_data* data, const struct part* p,
  * background.
  *
  * @param cooling The #cooling_function_data used in the run.
- * @param chemistry The #chemistry_data from grackle.
+ * @param chemistry The chemistry_data structure from grackle.
  * @param p Pointer to the particle data.
- *
+ * @param cosmo The #cosmology.
  */
 void cooling_apply_self_shielding(
     const struct cooling_function_data* restrict cooling,
@@ -568,6 +576,8 @@ void cooling_apply_self_shielding(
  *
  * @param phys_const The physical constants in internal units.
  * @param us The internal system of units.
+ * @param cosmo The #cosmology.
+ * @param hydro_props The #hydro_props.
  * @param cooling The #cooling_function_data used in the run.
  * @param p Pointer to the particle data.
  * @param xp Pointer to the particle extra data
@@ -641,6 +651,10 @@ gr_float cooling_new_energy(
 /**
  * @brief Compute the cooling time
  *
+ * @param phys_const The physical constants in internal units.
+ * @param us The internal system of units.
+ * @param hydro_props The #hydro_props.
+ * @param cosmo The #cosmology.
  * @param cooling The #cooling_function_data used in the run.
  * @param p Pointer to the particle data.
  * @param xp Pointer to the particle extra data
@@ -715,6 +729,7 @@ gr_float cooling_time(const struct phys_const* restrict phys_const,
  * @param phys_const The physical constants in internal units.
  * @param us The internal system of units.
  * @param cosmo The current cosmological model.
+ * @param hydro_props The #hydro_props.
  * @param floor_props Properties of the entropy floor.
  * @param cooling The #cooling_function_data used in the run.
  * @param p Pointer to the particle data.
@@ -846,9 +861,11 @@ float cooling_get_temperature(
  *
  * @param cooling The #cooling_function_data used in the run.
  * @param phys_const The physical constants in internal units.
- * @param cosmo The current cosmological model.
+ * @param cosmo The #cosmology.
  * @param us The internal system of units.
+ * @param hydro_props The #hydro_props.
  * @param p Pointer to the particle data.
+ * @param xp Pointer to the particle extra data
  */
 float cooling_timestep(const struct cooling_function_data* restrict cooling,
                        const struct phys_const* restrict phys_const,
@@ -877,6 +894,7 @@ void cooling_split_part(struct part* p, struct xpart* xp, double n) {
  * @brief Initialises the cooling unit system.
  *
  * @param us The current internal system of units.
+ * @param phys_const The #phys_const.
  * @param cooling The cooling properties to initialize
  */
 void cooling_init_units(const struct unit_system* us,

src/cooling/grackle/cooling_io.h

@@ -54,6 +54,7 @@ __attribute__((always_inline)) INLINE static void cooling_write_flavour(
  * @brief Specifies which particle fields to write to a dataset
  *
  * @param parts The particle array.
+ * @param xparts The extra particle array.
  * @param list The list of i/o properties to write.
  * @param cooling The #cooling_function_data
  *
@@ -138,6 +139,7 @@ __attribute__((always_inline)) INLINE static int cooling_write_particles(
  *
  * @param parameter_file The parser parameter file
  * @param cooling The cooling properties to initialize
+ * @param phys_const The #phys_const.
  */
 __attribute__((always_inline)) INLINE static void cooling_read_parameters(
     struct swift_params* parameter_file, struct cooling_function_data* cooling,

src/cooling/grackle/cooling_struct.h

@@ -23,7 +23,7 @@
 #include <grackle.h>
 
 /**
- * @file src/cooling/none/cooling_struct.h
+ * @file src/cooling/grackle/cooling_struct.h
  * @brief Empty infrastructure for the cases without cooling function
  */
 

src/feedback/GEAR/feedback.c

@@ -37,7 +37,7 @@
  *
  * @param p The #part to consider.
  * @param xp The #xpart to consider.
- * @param cosmo The #cosmology.
+ * @param e The #engine.
  */
 void feedback_update_part(struct part* restrict p, struct xpart* restrict xp,
                           const struct engine* restrict e) {
@@ -86,9 +86,13 @@ void feedback_update_part(struct part* restrict p, struct xpart* restrict xp,
 }
 
 /**
- * @Brief Should we do feedback for this star?
+ * @brief Should we do feedback for this star?
  *
  * @param sp The star to consider.
+ * @param feedback_props The #feedback_props.
+ * @param with_cosmology Is the cosmology switch on?
+ * @param cosmo The #cosmology.
+ * @param time The current time.
  */
 int feedback_will_do_feedback(const struct spart* sp,
                               const struct feedback_props* feedback_props,

src/feedback/GEAR/feedback.h

@@ -66,7 +66,9 @@ void feedback_clean(struct feedback_props* feedback);
 
 /**
  * @brief Writes the current model of feedback to the file
- * @param h_grpsph The HDF5 group in which to write
+ *
+ * @param feedback The #feedback_props.
+ * @param h_grp The HDF5 group in which to write
  */
 INLINE static void feedback_write_flavour(struct feedback_props* feedback,
                                           hid_t h_grp) {

src/feedback/GEAR/hdf5_functions.h

@@ -91,7 +91,7 @@ io_read_string_array_attribute(hid_t grp, const char *name, void *data,
 /**
  * @brief Open a group in the yields table (#h5_close_group needs to be called).
  *
- * @param params The @swift_params.
+ * @param params The #swift_params.
  * @param group_name The name of the group to open.
  * @param file_id (output) The id of the file opened.
  * @param group_id (output) The id of the group opened.

src/feedback/GEAR/interpolation.h

@@ -59,16 +59,16 @@ struct interpolation_1d {
 /**
  * @brief Initialize the #interpolation_1d.
  *
- * @params interp The #interpolation_1d.
- * @params xmin Minimal value of x (in log).
- * @params xmax Maximal value of x (in log).
- * @params N Requested number of values.
- * @params log_data_xmin The minimal value of the data (in log).
- * @params step_size The size of the x steps (in log).
- * @params N_data The number of element in the data.
- * @params data The data to interpolate (y).
- * @params N The number of element in data.
- * @params boundary_condition The type of #interpolate_boundary_condition.
+ * @param interp The #interpolation_1d.
+ * @param xmin Minimal value of x (in log).
+ * @param xmax Maximal value of x (in log).
+ * @param N Requested number of values.
+ * @param log_data_xmin The minimal value of the data (in log).
+ * @param step_size The size of the x steps (in log).
+ * @param N_data The number of element in the data.
+ * @param data The data to interpolate (y).
+ * @param N The number of element in data.
+ * @param boundary_condition The type of #interpolate_boundary_condition.
  */
 __attribute__((always_inline)) static INLINE void interpolate_1d_init(
     struct interpolation_1d *interp, float xmin, float xmax, int N,
@@ -138,8 +138,8 @@ __attribute__((always_inline)) static INLINE void interpolate_1d_init(
 /**
  * @brief Interpolate the data.
  *
- * @params interp The #interpolation_1d.
- * @params x The x value where to interpolate.
+ * @param interp The #interpolation_1d.
+ * @param x The x value where to interpolate.
  *
  * @return The interpolated value y.
  */
@@ -187,7 +187,7 @@ __attribute__((always_inline)) static INLINE float interpolate_1d(
 /**
  * @brief Print the data.
  *
- * @params interp The #interpolation_1d.
+ * @param interp The #interpolation_1d.
  */
 __attribute__((always_inline)) static INLINE void interpolate_1d_print(
     const struct interpolation_1d *interp) {
@@ -208,7 +208,7 @@ __attribute__((always_inline)) static INLINE void interpolate_1d_print(
 /**
  * @brief Cleanup the #interpolation_1d structure.
  *
- * @params interp The #interpolation_1d.
+ * @param interp The #interpolation_1d.
  */
 __attribute__((always_inline)) static INLINE void interpolate_1d_free(
     struct interpolation_1d *interp) {

src/feedback/GEAR/stellar_evolution.c

@@ -94,6 +94,7 @@ int stellar_evolution_compute_integer_number_supernovae(
  * (solMass)
  * @param m_end_step Mass of a star ending its life at the end of the step
  * (solMass)
+ * @param m_init Birth mass of the stellar particle (solMass).
  * @param number_snia_f (Floating) Number of SNIa produced by the stellar
  * particle.
  * @param number_snii_f (Floating) Number of SNII produced by the stellar
@@ -374,6 +375,7 @@ const char* stellar_evolution_get_element_name(const struct stellar_model* sm,
  * @brief Read the name of all the elements present in the tables.
  *
  * @param sm The #stellar_model.
+ * @param params The #swift_params.
  */
 void stellar_evolution_read_elements(struct stellar_model* sm,
                                      struct swift_params* params) {
@@ -423,7 +425,6 @@ void stellar_evolution_read_elements(struct stellar_model* sm,
  * @param phys_const The physical constants in the internal unit system.
  * @param us The internal unit system.
  * @param params The parsed parameters.
- * @param hydro_props The already read-in properties of the hydro scheme.
  * @param cosmo The cosmological model.
  */
 void stellar_evolution_props_init(struct stellar_model* sm,

src/feedback/GEAR/supernovae_ii.c

@@ -92,8 +92,8 @@ float supernovae_ii_get_number_per_unit_mass(const struct supernovae_ii *snii,
  * @brief Get the SNII yields per mass (Poirier version).
  *
  * @param snii The #supernovae_ii model.
- * @param m1 The lower mass in log.
- * @param m2 The upper mass in log.
+ * @param log_m1 The lower mass in log.
+ * @param log_m2 The upper mass in log.
  * @param yields The elements ejected (needs to be allocated).
  */
 void supernovae_ii_get_yields_from_integral(const struct supernovae_ii *snii,
@@ -127,8 +127,8 @@ void supernovae_ii_get_yields_from_raw(const struct supernovae_ii *snii,
  * @brief Get the ejected mass (non processed) per mass unit.
  *
  * @param snii The #supernovae_ii model.
- * @param m1 The lower mass in log.
- * @param m2 The upper mass in log.
+ * @param log_m1 The lower mass in log.
+ * @param log_m2 The upper mass in log.
  *
  * @return mass_ejected_processed The mass of non processsed elements.
  */
@@ -271,6 +271,7 @@ void supernovae_ii_read_yields_array(
  *
  * @param snii The #supernovae_ii model.
  * @param params The simulation parameters.
+ * @param phys_const The #phys_const.
  * @param sm The #stellar_model.
  */
 void supernovae_ii_read_yields(struct supernovae_ii *snii,
@@ -398,6 +399,7 @@ void supernovae_ii_init(struct supernovae_ii *snii,
  *
  * @param snii the struct
  * @param stream the file stream
+ * @param sm The #stellar_model.
  */
 void supernovae_ii_dump(const struct supernovae_ii *snii, FILE *stream,
                         const struct stellar_model *sm) {
@@ -473,6 +475,7 @@ void supernovae_ii_dump(const struct supernovae_ii *snii, FILE *stream,
  *
  * @param snii the struct
  * @param stream the file stream
+ * @param sm The #stellar_model.
  */
 void supernovae_ii_restore(struct supernovae_ii *snii, FILE *stream,
                            const struct stellar_model *sm) {

src/star_formation/GEAR/star_formation.h

@@ -40,14 +40,15 @@
  *
  * Use the star formation criterion given by eq. 3 in Revaz & Jablonka 2018.
  *
- * @param starform the star formation law properties to use.
  * @param p the gas particles.
  * @param xp the additional properties of the gas particles.
+ * @param starform the star formation law properties to use.
  * @param phys_const the physical constants in internal units.
  * @param cosmo the cosmological parameters and properties.
  * @param hydro_props The properties of the hydro scheme.
  * @param us The internal system of units.
  * @param cooling The cooling data struct.
+ * @param entropy_floor The #entropy_floor_properties.
  *
  */
 INLINE static int star_formation_is_star_forming(
@@ -210,14 +211,17 @@ INLINE static void star_formation_update_part_not_SFR(
  * @brief Copies the properties of the gas particle over to the
  * star particle.
  *
- * @param e The #engine
  * @param p the gas particles.
  * @param xp the additional properties of the gas particles.
  * @param sp the new created star particle with its properties.
+ * @param e The #engine
  * @param starform the star formation law properties to use.
- * @param phys_const the physical constants in internal units.
  * @param cosmo the cosmological parameters and properties.
- * @param with_cosmology if we run with cosmology.
+ * @param with_cosmology Are we running a cosmological simulation?
+ * @param phys_const the physical constants in internal units.
+ * @param hydro_props The #hydro_props.
+ * @param us The #unit_system.
+ * @param cooling The #cooling_function_data.
  * @param convert_part Did we convert a part (or spawned one)?
  */
 INLINE static void star_formation_copy_properties(

src/star_formation/GEAR/star_formation_io.h

@@ -85,6 +85,7 @@ star_formation_write_sparticles(const struct spart* sparts,
  * @param parameter_file The parsed parameter file
  * @param phys_const Physical constants in internal units
  * @param us The current internal system of units
+ * @param hydro_props The #hydro_props.
  * @param starform the star formation law properties to initialize
  *
  */

src/star_formation/GEAR/star_formation_logger.h

@@ -34,7 +34,6 @@
  * @brief Update the stellar quantities in the current cell after creating
  * the new star particle spart sp.
  *
- * @param time_step, the current time step of the simulation
  * @param sp new created star particle
  * @param sf the star_formation_history struct of the current cell
  */

src/stars/GEAR/stars.h

@@ -59,6 +59,9 @@ __attribute__((always_inline)) INLINE static void stars_init_spart(
  *
  * @param sp The particle to act upon.
  * @param stars_properties Properties of the stars model.
+ * @param with_cosmology Are we running a cosmological simulation?
+ * @param scale_factor The current scale factor.
+ * @param time The current time.
  */
 __attribute__((always_inline)) INLINE static void stars_first_init_spart(
     struct spart* sp, const struct stars_props* stars_properties,