tweak a few comments

Author: mabruzzo

src/clib/dynamic_api.cpp

@@ -99,8 +99,10 @@ constexpr param_list string_param_l_ = INIT_PAR_LIST(string_param_entries_);
 
 /// retrieves a pointer to the field of my_chemistry that's named ``name``.
 ///
-/// This returns a nullptr pointer if: my_chemistry is nullptr, the field doesn't
-/// exist, or the field doesn't have the specified type
+/// This returns a nullptr pointer if:
+/// - my_chemistry is nullptr
+/// - the field doesn't exist
+/// - the field doesn't have the specified type
 static void* get_field_ptr_(chemistry_data* my_chemistry, const char* name,
                             const param_list my_param_l)
 {
@@ -152,8 +154,9 @@ char** local_chemistry_data_access_string(chemistry_data* my_chemistry,
 // These are primarily needed for testing purposes and can be used for
 // serialization.
 
-// returns the name of the ``i``th parameter of the specified type. This returns
-// nullptr when there are ``i`` or fewer parameters of the specified type
+/// returns the name of the ``i``th parameter of the specified type. This
+/// returns nullptr when there are ``i`` or fewer parameters of the specified
+/// type
 static const char* param_name_(std::size_t i, const param_list my_param_list)
 { return (i < my_param_list.len) ? my_param_list.entries[i].name : nullptr; }
 
@@ -180,4 +183,4 @@ unsigned int grackle_num_params(const char* type_name){
   return 0;
 }
 
-} // extern "C"
+}  // extern "C"

src/clib/rate_utils.cpp

@@ -18,27 +18,6 @@
 #include "LUT.hpp"             // CollisionalRxnLUT
 #include "opaque_storage.hpp"  // gr_opaque_storage
 
-// In comparison to the dynamic API for accessing elements of chemistry_data,
-// we have explicitly opted NOT to make use of offsetof to access arbitrary
-// values within a struct.
-// -> while `offsetof` may lead to somewhat simpler code, the validity of using
-//    it with pointer-arithmetic to access members of structs is murky at best.
-//    - Things become murky when you consider that the C standard models an
-//      abstract machine and doesn't place the strongest (or clearest)
-//      constraints on a compiler when you start arbitrarily messing with
-//      memory
-//    - C's object model (and maybe also pointer provenance) is relevant
-// -> An extended discussion can be found in this stackoverflow answer and in
-//    the comments about the answer (https://stackoverflow.com/a/69936600).
-//    - the most compelling point is that it would be useless for the standard
-//      to define the `offsetof` if these semantics didn't work
-// -> In any case, I'm much more skeptical that valid C++ code can make use of
-//    offsetof in this fashion (the object model is stricter and C++ provides a
-//    other machinery to accomplish similar things). Since we want to support
-//    compilation with a C++ compiler, this is the most important point
-//    offsetof in this fashion
-//
-
 // we have reserved the right to change this value at any time
 enum { UNDEFINED_RATE_ID_ = 0 };