From 83c0e74f3c11bdd70e9b469ad8f20a40553bce9b Mon Sep 17 00:00:00 2001 From: Ewan Miller Date: Fri, 2 Aug 2024 05:52:59 -0400 Subject: [PATCH] document all headers with \\ @file so they show up in doxygen, make it so logo now shows up in doxygen html and not just as a hue bold html command, add some more documentation to the instrumentation header --- README.md | 5 +- doc/doxygen.config | 4 +- doc/nuTens-logo.png => nuTens-logo.png | Bin nuTens/instrumentation.hpp | 93 ++++++++++++++++----- nuTens/propagator/base-matter-solver.hpp | 2 + nuTens/propagator/const-density-solver.hpp | 2 + nuTens/propagator/constants.hpp | 4 +- nuTens/propagator/propagator.hpp | 2 + nuTens/tensors/dtypes.hpp | 7 ++ nuTens/tensors/tensor.hpp | 5 ++ 10 files changed, 98 insertions(+), 26 deletions(-) rename doc/nuTens-logo.png => nuTens-logo.png (100%) diff --git a/README.md b/README.md index 47f54a5..87ef6a3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ + -# nuTens +# nuTens +nuTens + nuTens is a software library which uses [tensors](https://en.wikipedia.org/wiki/Tensor_(machine_learning)) to efficiently calculate neutrino oscillation probabilities. diff --git a/doc/doxygen.config b/doc/doxygen.config index ddc7a1b..01b34eb 100644 --- a/doc/doxygen.config +++ b/doc/doxygen.config @@ -966,7 +966,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = ./doc # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1223,7 +1223,7 @@ HTML_EXTRA_STYLESHEET = doc/tweaks.css # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_FILES = +HTML_EXTRA_FILES = nuTens-logo.png # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to diff --git a/doc/nuTens-logo.png b/nuTens-logo.png similarity index 100% rename from doc/nuTens-logo.png rename to nuTens-logo.png diff --git a/nuTens/instrumentation.hpp b/nuTens/instrumentation.hpp index 7c6a4f8..931fbff 100644 --- a/nuTens/instrumentation.hpp +++ b/nuTens/instrumentation.hpp @@ -6,16 +6,19 @@ #include #include #include -/*! \file instrumentation.hpp - \brief Define utilities for instrumentation of the code - This is the home of anything that gets placed inside other classes or functions in order to instrument the code. - e.g. for profiling or debugging. Everything should ideally be macro-fied so it can be included only for certain - builds, or specified by build time options. -*/ +/*! + * @file instrumentation.hpp + * @brief Define utilities for instrumentation of the code + * + * This is the home of anything that gets placed inside other classes or functions in order to instrument the code. + * e.g. for profiling or debugging. Everything should ideally be macro-fied so it can be included only for certain + * builds, or specified by build time options. + */ struct ProfileResult { + /// @struct ProfileResult /// @brief Hold the results of a profiled function to be written out. std::string name; @@ -26,21 +29,64 @@ struct ProfileResult class ProfileWriter { - /*! @class ProfileWriter + /*! + * @class ProfileWriter * @brief Singleton class to collect timing information for functions and write out to a file that can be inspected * later with visual profiling tool * * Writes out profiling information in a json format readable by chrome tracing * (https://www.chromium.org/developers/how-tos/trace-event-profiling-tool/) Use the macros provided to instrument - * the code like: \code{.cpp} + * the source code like: + * + * @code{.cpp} + * \\ header.hpp + * + * class ClassName + * { + * returnType func(args); + * } + * + * + * \\ implementation.cpp + * + * ClassName::func(args) + * { + * NT_PROFILE(); + * + * \\ implementation code + * + * } + * @endcode + * + * In order to instantiate the ProfileWriter in an application you will then need to use NT_PROFILE_BEGINSESSION() + * and NT_PROFILE_ENDSESSION() like: + * + * @code{.cpp} + * + * \\ application.cpp + * + * void main() + * { + * NT_PROFILE_BEGINSESSION(sessionName); * - * \code{.cpp} + * \\ ... code ... + * ClassName instance; * - * Then open up your favourite chromium based browser and go to chrome://tracing. You can then just drag and drop - * the profiling json file and should see a lovely display of the collected profile information. + * instance.func(args); + * + * \\ ... code ... + * + * NT_PROFILE_ENDSSION(); + * } + * + * @endcode + * + * This will save a json file called -profile.json. + * Then you can open up your favourite chromium based browser and go to chrome://tracing. You can then just drag and + * drop the profiling json file and should see a lovely display of the collected profile information. */ - /// \todo currently only suppor the format used by chrome tracing. Would be nice to support other formats too. + /// @todo currently only suppor the format used by chrome tracing. Would be nice to support other formats too. /// Should just be a case of adding additional option for writeProfile and header and footer public: @@ -120,18 +166,21 @@ class ProfileWriter }; class InstrumentationTimer -/*! - * @class InstrumentationTimer - * @brief Class to perform the actual timing - * - * - * - */ { + /*! + * @class InstrumentationTimer + * @brief Class to perform timing + * + * Gets created at the start of the scope to time then will be deleted when the scope ends. + * When deleted, will write out timing information to the output stream defined by ProfileWriter. + * + * + */ + public: /// @brief Construct an InstrumentationTimer object and start the clock - /// @param[in] name The name of the profile. Typically use __FUNCSIG__ so it's clear which part of the code is being - /// profiled. + /// @param[in] name The name of the profile. Typically use __PRETTY_FUNCTION__ so it's clear which part of the code + /// is being profiled. InstrumentationTimer(std::string name) : _name(std::move(name)), _stopped(false) { _startTimepoint = std::chrono::high_resolution_clock::now(); @@ -182,6 +231,7 @@ class InstrumentationTimer #endif /// @brief Profile the current scope +/// Shold always be used at the very start of the scope. #ifdef USE_PROFILING // NOLINTNEXTLINE #define NT_PROFILE() InstrumentationTimer timer##__LINE__(std::string(__PRETTY_FUNCTION__)) @@ -190,6 +240,7 @@ class InstrumentationTimer #endif /// @brief End the profiling session +/// Should be used at the very end of an application, after all functions containing a NT_PROFILE() have been called #ifdef USE_PROFILING // NOLINTNEXTLINE #define NT_PROFILE_ENDSESSION() ProfileWriter::get().endSession() diff --git a/nuTens/propagator/base-matter-solver.hpp b/nuTens/propagator/base-matter-solver.hpp index c7fd5e7..69ec5e7 100644 --- a/nuTens/propagator/base-matter-solver.hpp +++ b/nuTens/propagator/base-matter-solver.hpp @@ -3,6 +3,8 @@ #include #include +/// @file base-matter-solver.hpp + class BaseMatterSolver { /// @class BaseMatterSolver diff --git a/nuTens/propagator/const-density-solver.hpp b/nuTens/propagator/const-density-solver.hpp index 3ff1e48..5df83a9 100644 --- a/nuTens/propagator/const-density-solver.hpp +++ b/nuTens/propagator/const-density-solver.hpp @@ -3,6 +3,8 @@ #include #include +/// @file const-density-solver.hpp + class ConstDensityMatterSolver : public BaseMatterSolver { /*! diff --git a/nuTens/propagator/constants.hpp b/nuTens/propagator/constants.hpp index 8b693c7..c4a7f36 100644 --- a/nuTens/propagator/constants.hpp +++ b/nuTens/propagator/constants.hpp @@ -1,8 +1,8 @@ #pragma once -/// @file constant.hpp +/// @file constants.hpp +/// @brief Defines constants to be used across the project -//! Define constants to be used across the project namespace Constants { diff --git a/nuTens/propagator/propagator.hpp b/nuTens/propagator/propagator.hpp index f949b76..b917aa2 100644 --- a/nuTens/propagator/propagator.hpp +++ b/nuTens/propagator/propagator.hpp @@ -5,6 +5,8 @@ #include #include +/// @file propagator.hpp + class Propagator { /*! diff --git a/nuTens/tensors/dtypes.hpp b/nuTens/tensors/dtypes.hpp index 1bde089..46d2508 100644 --- a/nuTens/tensors/dtypes.hpp +++ b/nuTens/tensors/dtypes.hpp @@ -1,8 +1,14 @@ #pragma once +/*! + * @file dtypes.hpp + * @brief Defines various datatypes used in the project + */ + namespace NTdtypes { +/// Types of scalar values enum scalarType { kInt, @@ -12,6 +18,7 @@ enum scalarType kComplexDouble, }; +/// Devices that a Tensor can live on enum deviceType { kCPU, diff --git a/nuTens/tensors/tensor.hpp b/nuTens/tensors/tensor.hpp index ae1e4ae..ba907d7 100644 --- a/nuTens/tensors/tensor.hpp +++ b/nuTens/tensors/tensor.hpp @@ -13,6 +13,11 @@ #include #endif +/*! + * @file tensor.hpp + * @brief Defines the interface of a Tensor object + */ + class Tensor { /*!