It might be worth making these doxygen style headers.  Certainly in the main code, less important for sim.