From 46508487a094703b405c5f50927e424bec683854 Mon Sep 17 00:00:00 2001 From: Kenneth Moreland Date: Mon, 12 Feb 2024 15:18:09 +0900 Subject: [PATCH] Fix doxygen warnings with worklet base classes Some versions of doxygen have issues with documenting `typedef`s (or the equivalent `using`). This was causing warnings with doxygen and failing to create some of the documentation. This fixes the problem by moving the documentation to the classes things are defined to. --- vtkm/exec/arg/InputIndex.h | 17 ++++++----- vtkm/exec/arg/OutputIndex.h | 16 +++++----- vtkm/exec/arg/ThreadIndices.h | 13 ++++---- vtkm/exec/arg/VisitIndex.h | 15 ++++++---- vtkm/exec/arg/WorkIndex.h | 14 ++++----- vtkm/worklet/Keys.h | 40 +++++++++++-------------- vtkm/worklet/WorkletCellNeighborhood.h | 10 +++---- vtkm/worklet/WorkletMapField.h | 10 +++---- vtkm/worklet/WorkletMapTopology.h | 20 ++++++------- vtkm/worklet/WorkletPointNeighborhood.h | 10 +++---- vtkm/worklet/WorkletReduceByKey.h | 10 +++---- vtkm/worklet/internal/WorkletBase.h | 29 ++++-------------- 12 files changed, 95 insertions(+), 109 deletions(-) diff --git a/vtkm/exec/arg/InputIndex.h b/vtkm/exec/arg/InputIndex.h index c71dd3eb2..5b8a7d9d0 100644 --- a/vtkm/exec/arg/InputIndex.h +++ b/vtkm/exec/arg/InputIndex.h @@ -20,9 +20,9 @@ namespace exec namespace arg { -/// \brief Aspect tag to use for getting the work index. +/// @brief Aspect tag to use for getting the work index. /// -/// The \c AspectTagInputIndex aspect tag causes the \c Fetch class to ignore +/// The `AspectTagInputIndex` aspect tag causes the \c Fetch class to ignore /// whatever data is in the associated execution object and return the index /// of the input element. /// @@ -30,15 +30,16 @@ struct AspectTagInputIndex { }; -/// \brief The \c ExecutionSignature tag to use to get the input index +/// @brief The `ExecutionSignature` tag to use to get the input index +/// +/// This tag produces a `vtkm::Id` that identifies the index of the input +/// element, which can differ from the `WorkIndex` in a worklet with a scatter. /// /// When a worklet is dispatched, it broken into pieces defined by the input -/// domain and scheduled on independent threads. This tag in the \c -/// ExecutionSignature passes the index of the input element that the work +/// domain and scheduled on independent threads. This tag in the +/// `ExecutionSignature` passes the index of the input element that the work /// thread is currently working on. When a worklet has a scatter associated -/// with it, the input and output indices can be different. \c WorkletBase -/// contains a typedef that points to this class. -/// +/// with it, the input and output indices can be different. struct InputIndex : vtkm::exec::arg::ExecutionSignatureTagBase { // The index does not really matter because the fetch is going to ignore it. diff --git a/vtkm/exec/arg/OutputIndex.h b/vtkm/exec/arg/OutputIndex.h index 1d426f57d..ecedea5de 100644 --- a/vtkm/exec/arg/OutputIndex.h +++ b/vtkm/exec/arg/OutputIndex.h @@ -20,9 +20,9 @@ namespace exec namespace arg { -/// \brief Aspect tag to use for getting the work index. +/// @brief Aspect tag to use for getting the work index. /// -/// The \c AspectTagOutputIndex aspect tag causes the \c Fetch class to ignore +/// The `AspectTagOutputIndex` aspect tag causes the `Fetch` class to ignore /// whatever data is in the associated execution object and return the index /// of the output element. /// @@ -30,14 +30,16 @@ struct AspectTagOutputIndex { }; -/// \brief The \c ExecutionSignature tag to use to get the output index +/// @brief The `ExecutionSignature` tag to use to get the output index +/// +/// This tag produces a `vtkm::Id` that identifies the index of the output element. +/// (This is generally the same as `WorkIndex`.) /// /// When a worklet is dispatched, it broken into pieces defined by the output -/// domain and scheduled on independent threads. This tag in the \c -/// ExecutionSignature passes the index of the output element that the work +/// domain and scheduled on independent threads. This tag in the +/// `ExecutionSignature` passes the index of the output element that the work /// thread is currently working on. When a worklet has a scatter associated -/// with it, the output and output indices can be different. \c WorkletBase -/// contains a typedef that points to this class. +/// with it, the output and output indices can be different. /// struct OutputIndex : vtkm::exec::arg::ExecutionSignatureTagBase { diff --git a/vtkm/exec/arg/ThreadIndices.h b/vtkm/exec/arg/ThreadIndices.h index 90f6be812..e4dae5bf3 100644 --- a/vtkm/exec/arg/ThreadIndices.h +++ b/vtkm/exec/arg/ThreadIndices.h @@ -20,9 +20,9 @@ namespace exec namespace arg { -/// \brief Aspect tag to use for getting the thread indices. +/// @brief Aspect tag to use for getting the thread indices. /// -/// The \c AspectTagThreadIndices aspect tag causes the \c Fetch class to +/// The `AspectTagThreadIndices` aspect tag causes the `Fetch` class to /// ignore whatever data is in the associated execution object and return the /// thread indices. /// @@ -30,13 +30,16 @@ struct AspectTagThreadIndices { }; -/// \brief The \c ExecutionSignature tag to use to get the thread indices +/// @brief The `ExecutionSignature` tag to use to get the thread indices +/// +/// This tag produces an internal object that manages indices and other metadata +/// of the current thread. Thread indices objects vary by worklet type, but most +/// users can get the information they need through other signature tags. /// /// When a worklet is dispatched, it broken into pieces defined by the input /// domain and scheduled on independent threads. During this process multiple /// indices associated with the input and output can be generated. This tag in -/// the \c ExecutionSignature passes the index for this work. \c WorkletBase -/// contains a typedef that points to this class. +/// the `ExecutionSignature` passes the index for this work. /// struct ThreadIndices : vtkm::exec::arg::ExecutionSignatureTagBase { diff --git a/vtkm/exec/arg/VisitIndex.h b/vtkm/exec/arg/VisitIndex.h index 7be61cf7e..60f4747b1 100644 --- a/vtkm/exec/arg/VisitIndex.h +++ b/vtkm/exec/arg/VisitIndex.h @@ -20,9 +20,9 @@ namespace exec namespace arg { -/// \brief Aspect tag to use for getting the work index. +/// @brief Aspect tag to use for getting the work index. /// -/// The \c AspectTagVisitIndex aspect tag causes the \c Fetch class to ignore +/// The `AspectTagVisitIndex` aspect tag causes the `Fetch` class to ignore /// whatever data is in the associated execution object and return the visit /// index. /// @@ -30,15 +30,18 @@ struct AspectTagVisitIndex { }; -/// \brief The \c ExecutionSignature tag to use to get the visit index +/// @brief The `ExecutionSignature` tag to use to get the visit index +/// +/// This tag produces a `vtkm::IdComponent` that uniquely identifies when multiple +/// worklet invocations operate on the same input item, which can happen when +/// defining a worklet with scatter. /// /// When a worklet is dispatched, there is a scatter operation defined that /// optionally allows each input to go to multiple output entries. When one /// input is assigned to multiple outputs, there needs to be a mechanism to /// uniquely identify which output is which. The visit index is a value between -/// 0 and the number of outputs a particular input goes to. This tag in the \c -/// ExecutionSignature passes the visit index for this work. \c WorkletBase -/// contains a typedef that points to this class. +/// 0 and the number of outputs a particular input goes to. This tag in the +/// `ExecutionSignature` passes the visit index for this work. /// struct VisitIndex : vtkm::exec::arg::ExecutionSignatureTagBase { diff --git a/vtkm/exec/arg/WorkIndex.h b/vtkm/exec/arg/WorkIndex.h index c4799a5f6..d16ed65e6 100644 --- a/vtkm/exec/arg/WorkIndex.h +++ b/vtkm/exec/arg/WorkIndex.h @@ -20,22 +20,22 @@ namespace exec namespace arg { -/// \brief Aspect tag to use for getting the work index. +/// @brief Aspect tag to use for getting the work index. /// -/// The \c AspectTagWorkIndex aspect tag causes the \c Fetch class to ignore +/// The `AspectTagWorkIndex` aspect tag causes the `Fetch` class to ignore /// whatever data is in the associated execution object and return the index. /// struct AspectTagWorkIndex { }; -/// \brief The \c ExecutionSignature tag to use to get the work index +/// @brief The `ExecutionSignature` tag to use to get the work index /// +/// This tag produces a `vtkm::Id` that uniquely identifies the invocation +/// instance of the worklet. /// When a worklet is dispatched, it broken into pieces defined by the input -/// domain and scheduled on independent threads. This tag in the \c -/// ExecutionSignature passes the index for this work. \c WorkletBase contains -/// a typedef that points to this class. -/// +/// domain and scheduled on independent threads. This tag in the +/// `ExecutionSignature` passes the index for this work. struct WorkIndex : vtkm::exec::arg::ExecutionSignatureTagBase { // The index does not really matter because the fetch is going to ignore it. diff --git a/vtkm/worklet/Keys.h b/vtkm/worklet/Keys.h index 40c408bce..e4507f72b 100644 --- a/vtkm/worklet/Keys.h +++ b/vtkm/worklet/Keys.h @@ -52,27 +52,12 @@ public: KeysBase& operator=(const KeysBase&) = default; ~KeysBase() = default; - /// @brief Returns the input range of a keys object when used as an input domain. - /// - /// This will be equal to the number of unique keys. VTKM_CONT vtkm::Id GetInputRange() const { return this->Offsets.GetNumberOfValues() - 1; } - /// @brief Returns the array that maps each input value to an array of sorted keys. - /// - /// This array is used internally as the indices to a `vtkm::cont::ArrayHandlePermutation` - /// to order input values with the grouped keys so that they can then be grouped. This is - /// an internal array that is seldom of use to code outside the - /// `vtkm::worklet::WorkletReduceByKey` implementation. VTKM_CONT vtkm::cont::ArrayHandle GetSortedValuesMap() const { return this->SortedValuesMap; } - /// @brief Returns an offsets array to group keys. - /// - /// Given an array of sorted keys (or more frequently values permuted to the sorting of - /// the keys), this array of indices can be used as offsets for a - /// `vtkm::cont::ArrayHandleGroupVecVariable`. This is an internal array that is seldom of - /// use to code outside the `vtkm::worklet::WorkletReduceByKey` implementation. VTKM_CONT vtkm::cont::ArrayHandle GetOffsets() const { return this->Offsets; } @@ -80,9 +65,6 @@ public: VTKM_CONT vtkm::cont::ArrayHandle GetCounts() const; - /// @brief Returns the number of input keys and values used to build this structure. - /// - /// This is also the size of input arrays to a `vtkm::worklet::WorkletReduceByKey`. VTKM_CONT vtkm::Id GetNumberOfValues() const { return this->SortedValuesMap.GetNumberOfValues(); } @@ -196,16 +178,30 @@ public: #ifdef VTKM_DOXYGEN_ONLY // Document the superclass' methods as methods in this class. - /// @copydoc vtkm::worklet::internal::KeysBase::GetInputRange + /// @brief Returns the input range of a keys object when used as an input domain. + /// + /// This will be equal to the number of unique keys. vtkm::Id GetInputRange() const; - /// @copydoc vtkm::worklet::internal::KeysBase::GetSortedValuesMap + /// @brief Returns the array that maps each input value to an array of sorted keys. + /// + /// This array is used internally as the indices to a `vtkm::cont::ArrayHandlePermutation` + /// to order input values with the grouped keys so that they can then be grouped. This is + /// an internal array that is seldom of use to code outside the + /// `vtkm::worklet::WorkletReduceByKey` implementation. vtkm::cont::ArrayHandle GetSortedValuesMap() const; - /// @copydoc vtkm::worklet::internal::KeysBase::GetOffsets + /// @brief Returns an offsets array to group keys. + /// + /// Given an array of sorted keys (or more frequently values permuted to the sorting of + /// the keys), this array of indices can be used as offsets for a + /// `vtkm::cont::ArrayHandleGroupVecVariable`. This is an internal array that is seldom of + /// use to code outside the `vtkm::worklet::WorkletReduceByKey` implementation. vtkm::cont::ArrayHandle GetOffsets() const; - /// @copydoc vtkm::worklet::internal::KeysBase::GetNumberOfValues + /// @brief Returns the number of input keys and values used to build this structure. + /// + /// This is also the size of input arrays to a `vtkm::worklet::WorkletReduceByKey`. vtkm::Id GetNumberOfValues() const; #endif diff --git a/vtkm/worklet/WorkletCellNeighborhood.h b/vtkm/worklet/WorkletCellNeighborhood.h index 75b21f648..541f94549 100644 --- a/vtkm/worklet/WorkletCellNeighborhood.h +++ b/vtkm/worklet/WorkletCellNeighborhood.h @@ -120,27 +120,27 @@ public: { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::WorkIndex + /// @copydoc vtkm::exec::arg::WorkIndex struct WorkIndex : vtkm::worklet::internal::WorkletBase::WorkIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::VisitIndex + /// @copydoc vtkm::exec::arg::VisitIndex struct VisitIndex : vtkm::worklet::internal::WorkletBase::VisitIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::InputIndex + /// @copydoc vtkm::exec::arg::InputIndex struct InputIndex : vtkm::worklet::internal::WorkletBase::InputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::OutputIndex + /// @copydoc vtkm::exec::arg::OutputIndex struct OutputIndex : vtkm::worklet::internal::WorkletBase::OutputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::ThreadIndices + /// @copydoc vtkm::exec::arg::ThreadIndices struct ThreadIndices : vtkm::worklet::internal::WorkletBase::ThreadIndices { }; diff --git a/vtkm/worklet/WorkletMapField.h b/vtkm/worklet/WorkletMapField.h index c837f9949..9599f4a4d 100644 --- a/vtkm/worklet/WorkletMapField.h +++ b/vtkm/worklet/WorkletMapField.h @@ -153,27 +153,27 @@ public: { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::WorkIndex + /// @copydoc vtkm::exec::arg::WorkIndex struct WorkIndex : vtkm::worklet::internal::WorkletBase::WorkIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::VisitIndex + /// @copydoc vtkm::exec::arg::VisitIndex struct VisitIndex : vtkm::worklet::internal::WorkletBase::VisitIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::InputIndex + /// @copydoc vtkm::exec::arg::InputIndex struct InputIndex : vtkm::worklet::internal::WorkletBase::InputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::OutputIndex + /// @copydoc vtkm::exec::arg::OutputIndex struct OutputIndex : vtkm::worklet::internal::WorkletBase::OutputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::ThreadIndices + /// @copydoc vtkm::exec::arg::ThreadIndices struct ThreadIndices : vtkm::worklet::internal::WorkletBase::ThreadIndices { }; diff --git a/vtkm/worklet/WorkletMapTopology.h b/vtkm/worklet/WorkletMapTopology.h index cd9cfc04d..7da97d387 100644 --- a/vtkm/worklet/WorkletMapTopology.h +++ b/vtkm/worklet/WorkletMapTopology.h @@ -419,27 +419,27 @@ public: { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::WorkIndex + /// @copydoc vtkm::exec::arg::WorkIndex struct WorkIndex : vtkm::worklet::internal::WorkletBase::WorkIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::VisitIndex + /// @copydoc vtkm::exec::arg::VisitIndex struct VisitIndex : vtkm::worklet::internal::WorkletBase::VisitIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::InputIndex + /// @copydoc vtkm::exec::arg::InputIndex struct InputIndex : vtkm::worklet::internal::WorkletBase::InputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::OutputIndex + /// @copydoc vtkm::exec::arg::OutputIndex struct OutputIndex : vtkm::worklet::internal::WorkletBase::OutputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::ThreadIndices + /// @copydoc vtkm::exec::arg::ThreadIndices struct ThreadIndices : vtkm::worklet::internal::WorkletBase::ThreadIndices { }; @@ -612,27 +612,27 @@ public: { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::WorkIndex + /// @copydoc vtkm::exec::arg::WorkIndex struct WorkIndex : vtkm::worklet::internal::WorkletBase::WorkIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::VisitIndex + /// @copydoc vtkm::exec::arg::VisitIndex struct VisitIndex : vtkm::worklet::internal::WorkletBase::VisitIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::InputIndex + /// @copydoc vtkm::exec::arg::InputIndex struct InputIndex : vtkm::worklet::internal::WorkletBase::InputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::OutputIndex + /// @copydoc vtkm::exec::arg::OutputIndex struct OutputIndex : vtkm::worklet::internal::WorkletBase::OutputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::ThreadIndices + /// @copydoc vtkm::exec::arg::ThreadIndices struct ThreadIndices : vtkm::worklet::internal::WorkletBase::ThreadIndices { }; diff --git a/vtkm/worklet/WorkletPointNeighborhood.h b/vtkm/worklet/WorkletPointNeighborhood.h index 1052ff49d..fb7946877 100644 --- a/vtkm/worklet/WorkletPointNeighborhood.h +++ b/vtkm/worklet/WorkletPointNeighborhood.h @@ -116,27 +116,27 @@ public: { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::WorkIndex + /// @copydoc vtkm::exec::arg::WorkIndex struct WorkIndex : vtkm::worklet::internal::WorkletBase::WorkIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::VisitIndex + /// @copydoc vtkm::exec::arg::VisitIndex struct VisitIndex : vtkm::worklet::internal::WorkletBase::VisitIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::InputIndex + /// @copydoc vtkm::exec::arg::InputIndex struct InputIndex : vtkm::worklet::internal::WorkletBase::InputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::OutputIndex + /// @copydoc vtkm::exec::arg::OutputIndex struct OutputIndex : vtkm::worklet::internal::WorkletBase::OutputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::ThreadIndices + /// @copydoc vtkm::exec::arg::ThreadIndices struct ThreadIndices : vtkm::worklet::internal::WorkletBase::ThreadIndices { }; diff --git a/vtkm/worklet/WorkletReduceByKey.h b/vtkm/worklet/WorkletReduceByKey.h index 4b35a357a..5df810800 100644 --- a/vtkm/worklet/WorkletReduceByKey.h +++ b/vtkm/worklet/WorkletReduceByKey.h @@ -253,27 +253,27 @@ public: #ifdef VTKM_DOXYGEN_ONLY // These redeclarations of superclass features are for documentation purposes only. - /// @copydoc vtkm::worklet::internal::WorkletBase::WorkIndex + /// @copydoc vtkm::exec::arg::WorkIndex struct WorkIndex : vtkm::worklet::internal::WorkletBase::WorkIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::VisitIndex + /// @copydoc vtkm::exec::arg::VisitIndex struct VisitIndex : vtkm::worklet::internal::WorkletBase::VisitIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::InputIndex + /// @copydoc vtkm::exec::arg::InputIndex struct InputIndex : vtkm::worklet::internal::WorkletBase::InputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::OutputIndex + /// @copydoc vtkm::exec::arg::OutputIndex struct OutputIndex : vtkm::worklet::internal::WorkletBase::OutputIndex { }; - /// @copydoc vtkm::worklet::internal::WorkletBase::ThreadIndices + /// @copydoc vtkm::exec::arg::ThreadIndices struct ThreadIndices : vtkm::worklet::internal::WorkletBase::ThreadIndices { }; diff --git a/vtkm/worklet/internal/WorkletBase.h b/vtkm/worklet/internal/WorkletBase.h index b3c694019..cdf669cbf 100644 --- a/vtkm/worklet/internal/WorkletBase.h +++ b/vtkm/worklet/internal/WorkletBase.h @@ -79,38 +79,19 @@ public: using _19 = vtkm::placeholders::Arg<19>; using _20 = vtkm::placeholders::Arg<20>; - /// @brief `ExecutionSignature` tag for getting the work index. - /// - /// This tag produces a `vtkm::Id` that uniquely identifies the invocation - /// instance of the worklet. - /// + /// @copydoc vtkm::exec::arg::WorkIndex using WorkIndex = vtkm::exec::arg::WorkIndex; - /// @brief `ExecutionSignature` tag for getting the input index. - /// - /// This tag produces a `vtkm::Id` that identifies the index of the input - /// element, which can differ from the `WorkIndex` in a worklet with a scatter. + /// @copydoc vtkm::exec::arg::InputIndex using InputIndex = vtkm::exec::arg::InputIndex; - /// @brief `ExecutionSignature` tag for getting the output index. - /// - /// This tag produces a `vtkm::Id` that identifies the index of the output element. - /// (This is generally the same as `WorkIndex`.) + /// @copydoc vtkm::exec::arg::OutputIndex using OutputIndex = vtkm::exec::arg::OutputIndex; - /// @brief `ExecutionSignature` tag for getting the thread indices. - /// - /// This tag produces an internal object that manages indices and other metadata - /// of the current thread. Thread indices objects vary by worklet type, but most - /// users can get the information they need through other signature tags. + /// @copydoc vtkm::exec::arg::ThreadIndices using ThreadIndices = vtkm::exec::arg::ThreadIndices; - /// @brief `ExecutionSignature` tag for getting the visit index. - /// - /// This tag produces a `vtkm::IdComponent` that uniquely identifies when multiple - /// worklet invocations operate on the same input item, which can happen when - /// defining a worklet with scatter. - /// + /// @copydoc vtkm::exec::arg::VisitIndex using VisitIndex = vtkm::exec::arg::VisitIndex; /// @brief `ExecutionSignature` tag for getting the device adapter tag.