From 0c65e11d09000bae3541e3806f571513325b2661 Mon Sep 17 00:00:00 2001 From: Eduard Valeyev Date: Sun, 25 Feb 2024 23:52:28 -0500 Subject: [PATCH] dox cleanup --- doc/dox/config/Doxyfile.in | 2 +- ttg/ttg/base/tt.h | 1 - ttg/ttg/func.h | 37 ++++++++++++++++++---------------- ttg/ttg/madness/ttg.h | 4 ++-- ttg/ttg/parsec/ttg.h | 4 ++-- ttg/ttg/serialization/traits.h | 2 +- ttg/ttg/terminal.h | 1 + ttg/ttg/util/bug.h | 3 +-- ttg/ttg/util/iovec.h | 5 ++--- 9 files changed, 30 insertions(+), 29 deletions(-) diff --git a/doc/dox/config/Doxyfile.in b/doc/dox/config/Doxyfile.in index a1154935d..cdf1a56f1 100644 --- a/doc/dox/config/Doxyfile.in +++ b/doc/dox/config/Doxyfile.in @@ -399,7 +399,7 @@ DISTRIBUTE_GROUP_DOC = YES # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. -GROUP_NESTED_COMPOUNDS = NO +GROUP_NESTED_COMPOUNDS = YES # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that diff --git a/ttg/ttg/base/tt.h b/ttg/ttg/base/tt.h index c686bee2a..d2fbd467a 100644 --- a/ttg/ttg/base/tt.h +++ b/ttg/ttg/base/tt.h @@ -264,7 +264,6 @@ namespace ttg { virtual void release() {} /// Marks this executable - /// @return nothing virtual void make_executable() = 0; /// Queries if this ready to execute diff --git a/ttg/ttg/func.h b/ttg/ttg/func.h index e1394be89..28b75ace9 100644 --- a/ttg/ttg/func.h +++ b/ttg/ttg/func.h @@ -98,11 +98,14 @@ namespace ttg { inline void connect(ttg::TerminalBase *out, ttg::TerminalBase *in) { out->connect(in); } /// \brief Connect producer output terminal outindex to consumer input terminal inindex (via unique or otherwise - /// wrapped pointers to TTs) \tparam outindex The index of the output terminal on the producer. \tparam inindex The - /// index of the input terminal on the consumer. \param p The producer TT \param c The consumer TT + /// wrapped pointers to TTs) + /// \tparam outindex The index of the output terminal on the producer. + /// \tparam inindex The index of the input terminal on the consumer. + /// \param p The producer TT + /// \param c The consumer TT template - inline void connect(producer_tt_ptr &p, successor_tt_ptr &s) { - connect(p->template out(), s->template in()); + inline void connect(producer_tt_ptr &p, successor_tt_ptr &c) { + connect(p->template out(), c->template in()); } /// \brief Connect producer output terminal outindex to consumer input terminal inindex (via bare pointers to TTs) @@ -111,13 +114,13 @@ namespace ttg { /// \param p The producer TT /// \param c The consumer TT template - inline void connect(producer_tt_ptr *p, successor_tt_ptr *s) { - connect(p->template out(), s->template in()); + inline void connect(producer_tt_ptr *p, successor_tt_ptr *c) { + connect(p->template out(), c->template in()); } /// \brief Connect producer output terminal outindex to consumer input terminal inindex (via TTBase pointers) - /// \tparam outindex The index of the output terminal on the producer. - /// \tparam inindex The index of the input terminal on the consumer. + /// \param outindex The index of the output terminal on the producer. + /// \param inindex The index of the input terminal on the consumer. /// \param producer The producer TT /// \param consumer The consumer TT inline void connect(size_t outindex, size_t inindex, TTBase *producer, TTBase *consumer) { @@ -149,7 +152,7 @@ namespace ttg { /// \brief Sends a task id and a value to the given output terminal /// \param[in] key: the id of the task(s) receiving the value /// \param[in] value: the value to send to the receiving task(s) - /// \param[in] out: the output terminal + /// \param[in] t: the output terminal // clang-format on template inline void send(const keyT &key, valueT &&value, ttg::Out &t) { @@ -160,7 +163,7 @@ namespace ttg { // clang-format off /// \brief Sends a task id (without an accompanying value) to the given output terminal /// \param[in] key: the id of the task(s) receiving the value - /// \param[in] out: the output terminal + /// \param[in] t: the output terminal // clang-format on template inline void sendk(const keyT &key, ttg::Out &t) { @@ -170,7 +173,7 @@ namespace ttg { // clang-format off /// \brief Sends a value (without an accompanying task id) to the given output terminal /// \param[in] value: the value to send to the receiving task(s) - /// \param[in] out: the output terminal + /// \param[in] t: the output terminal // clang-format on template inline void sendv(valueT &&value, ttg::Out &t) { @@ -180,7 +183,7 @@ namespace ttg { // clang-format off /// \brief Sends a control message (message without an accompanying task id or a value) to the given output terminal - /// \param[in] out: the output terminal + /// \param[in] t: the output terminal // clang-format on inline void send(ttg::Out &t) { t.send(); } @@ -189,7 +192,7 @@ namespace ttg { /// \tparam Identifies which output terminal in \p t to select for sending /// \param[in] key: the id of the task(s) receiving the value /// \param[in] value: the value to send to the receiving task(s) - /// \param[in] out: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) + /// \param[in] t: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) // clang-format on template @@ -230,7 +233,7 @@ namespace ttg { /// \brief Sends a task id (without an accompanying value) to the template tasks attached to the output terminal selected in the explicitly given terminal tuple \p t /// \tparam Identifies which output terminal in \p t to select for sending /// \param[in] key: the id of the task(s) receiving the value - /// \param[in] out: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) + /// \param[in] t: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) // clang-format on template inline std::enable_if_t, void> sendk(const keyT &key, @@ -264,7 +267,7 @@ namespace ttg { /// \brief Sends a value (without an accompanying task id) to the template tasks attached to the output terminal selected in the explicitly given terminal tuple \p t /// \tparam Identifies which output terminal in \p t to select for sending /// \param[in] value: the value to send to the receiving task(s) - /// \param[in] out: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) + /// \param[in] t: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) // clang-format on template @@ -276,7 +279,7 @@ namespace ttg { // clang-format off /// \brief Sends a value (without an accompanying task id) to the template tasks attached to the output terminal of this template task - /// \param[in] i Identifies which output terminal of this template task to select for sending + /// \param[in] Identifies which output terminal of this template task to select for sending /// \param[in] value: the value to send to the receiving task(s) // clang-format on template @@ -300,7 +303,7 @@ namespace ttg { // clang-format off /// \brief Sends a control message (message without an accompanying task id or a value) to the template tasks attached to the output terminal selected in the explicitly given terminal tuple \p t /// \tparam Identifies which output terminal in \p t to select for sending - /// \param[in] out: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) + /// \param[in] t: a tuple of output terminals (typically, this is the output terminal of the template task where this is invoked) // clang-format on template inline void send(std::tuple...> &t) { diff --git a/ttg/ttg/madness/ttg.h b/ttg/ttg/madness/ttg.h index 8dfc46971..2a0f46169 100644 --- a/ttg/ttg/madness/ttg.h +++ b/ttg/ttg/madness/ttg.h @@ -1164,7 +1164,7 @@ namespace ttg_madness { /// define the reducer function to be called when additional inputs are /// received on a streaming terminal /// @tparam the index of the input terminal that is used as a streaming terminal - /// @param[in] reducer: a function of prototype (input_type &a, const input_type &b) + /// @param[in] reducer: a function of prototype `void(input_type &a, const input_type &b)` /// that function should aggregate b into a template void set_input_reducer(Reducer &&reducer) { @@ -1175,7 +1175,7 @@ namespace ttg_madness { /// define the reducer function to be called when additional inputs are /// received on a streaming terminal /// @tparam the index of the input terminal that is used as a streaming terminal - /// @param[in] reducer: a function of prototype (input_type &a, const input_type &b) + /// @param[in] reducer: a function of prototype `void(input_type &a, const input_type &b)` /// that function should aggregate b into a /// @param[in] size: the default number of inputs that are received in this streaming terminal, /// for each task diff --git a/ttg/ttg/parsec/ttg.h b/ttg/ttg/parsec/ttg.h index 50072b2f7..2f10d75d3 100644 --- a/ttg/ttg/parsec/ttg.h +++ b/ttg/ttg/parsec/ttg.h @@ -3936,7 +3936,7 @@ ttg::abort(); // should not happen /// define the reducer function to be called when additional inputs are /// received on a streaming terminal /// @tparam the index of the input terminal that is used as a streaming terminal - /// @param[in] reducer: a function of prototype (input_type &a, const input_type &b) + /// @param[in] reducer: a function of prototype `void(input_type &a, const input_type &b)` /// that function should aggregate b into a template void set_input_reducer(Reducer &&reducer) { @@ -4015,7 +4015,7 @@ ttg::abort(); // should not happen /// define the reducer function to be called when additional inputs are /// received on a streaming terminal /// @tparam the index of the input terminal that is used as a streaming terminal - /// @param[in] reducer: a function of prototype (input_type &a, const input_type &b) + /// @param[in] reducer: a function of prototype `void(input_type &a, const input_type &b)` /// that function should aggregate b into a /// @param[in] size: the default number of inputs that are received in this streaming terminal, /// for each task diff --git a/ttg/ttg/serialization/traits.h b/ttg/ttg/serialization/traits.h index bd6d8f825..bf70298d6 100644 --- a/ttg/ttg/serialization/traits.h +++ b/ttg/ttg/serialization/traits.h @@ -23,7 +23,7 @@ namespace ttg::detail { /// helps to detect that `T` has a member serialization method that /// accepts single argument of type `Archive` - /// @note use in combination with `ttg::meta`::is_detected_v + /// @note use in combination with ttg::meta::is_detected_v template using has_member_serialize_t = decltype(std::declval().serialize(std::declval())); diff --git a/ttg/ttg/terminal.h b/ttg/ttg/terminal.h index 8711b3b06..dc9f4b08b 100644 --- a/ttg/ttg/terminal.h +++ b/ttg/ttg/terminal.h @@ -188,6 +188,7 @@ namespace ttg { /// will continue adding data onto this terminal /// \param[in] setsize_callback: if the terminal is a reduce terminal, announces how many items will be set /// unto this terminal for reduction + /// \param[in] prepare_send_callback: for resumable/device tasks this is called before actual send void set_callback(const send_callback_type &send_callback, const move_callback_type &move_callback, const broadcast_callback_type &bcast_callback = broadcast_callback_type{}, const setsize_callback_type &setsize_callback = setsize_callback_type{}, diff --git a/ttg/ttg/util/bug.h b/ttg/ttg/util/bug.h index 25f831191..1404fa01a 100644 --- a/ttg/ttg/util/bug.h +++ b/ttg/ttg/util/bug.h @@ -286,12 +286,11 @@ namespace ttg { static std::shared_ptr default_debugger_; - /** prints out a backtrace + /** prints out a backtrace to `std::cout` * * @param prefix this string will be prepended at the beginning of each line * of Backtrace * @param reason optional string specifying the reason for traceback - * @return backtrace */ static void __traceback(const std::string &prefix, const char *reason = nullptr); diff --git a/ttg/ttg/util/iovec.h b/ttg/ttg/util/iovec.h index 2a8d672b3..ad20d066d 100644 --- a/ttg/ttg/util/iovec.h +++ b/ttg/ttg/util/iovec.h @@ -7,12 +7,11 @@ namespace ttg { /** * Used to describe transfer payload in types using the \sa SplitMetadataDescriptor. - * @member data Pointer to the data to be read from / written to. - * @member num_bytes The number of bytes to read from / write to the memory location - * \sa data. */ struct iovec { + /// The number of bytes to read from / write to the memory location given by `data`. std::size_t num_bytes; + /// Pointer to the data to be read from / written to. void* data; };