From 6c9da6da339227bbce87c1312b10b296a7357e00 Mon Sep 17 00:00:00 2001 From: Ben-Bingham Date: Fri, 10 May 2024 20:58:39 -0600 Subject: [PATCH 1/5] Add documentation for both OSP_DECLARE_*_DATA_IDS macros --- src/osp/tasks/top_session.h | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/src/osp/tasks/top_session.h b/src/osp/tasks/top_session.h index 855b1b20..76e38e7e 100644 --- a/src/osp/tasks/top_session.h +++ b/src/osp/tasks/top_session.h @@ -45,7 +45,13 @@ #define OSP_AUX_DCDI_A(...) OSP_AUX_DCDI_B(OSP_AUX_DCDI_C(__VA_ARGS__)) /** - * @brief + * @brief Gives the next available section of topData to a session + * and declares an ID variable for each element that is given. + * The same ID's are also stored inside of the sessions m_data member + * + * @param arglist A variadic argument broken into two sections: + * Firstly: 'count' The count is an integer equal to the number of id's + * Secondly: id's Every id is a unique index into 'topData' */ #define OSP_DECLARE_CREATE_DATA_IDS(session, topData, arglist) OSP_AUX_DCDI_A(session, topData, arglist); @@ -55,6 +61,17 @@ #define OSP_AUX_DGDI_B(x) x #define OSP_AUX_DGDI_A(...) OSP_AUX_DGDI_B(OSP_AUX_DGDI_C(__VA_ARGS__)) +/** + * @brief Retrieves a section of data within topData that was already given to a session + * and maps an ID variable to each element that is retrieved. + * + * Because the data was already given, the indices are stored within the session and topData does + * not need to be accessed. + * + * @param arglist A variadic argument broken into two sections: + * Firstly: 'count' The count is an integer equal to the number of id's + * Secondly: id's Every id is a unique index into 'topData' + */ #define OSP_DECLARE_GET_DATA_IDS(session, arglist) OSP_AUX_DGDI_A(session, arglist); namespace osp From e705df9a906d817e010b3ae93cf86cf29d58f553 Mon Sep 17 00:00:00 2001 From: Ben-Bingham Date: Fri, 10 May 2024 21:18:27 -0600 Subject: [PATCH 2/5] Add documentation to top_utils.h --- src/osp/tasks/top_utils.h | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/src/osp/tasks/top_utils.h b/src/osp/tasks/top_utils.h index 2367af8d..4d0244a1 100644 --- a/src/osp/tasks/top_utils.h +++ b/src/osp/tasks/top_utils.h @@ -41,6 +41,11 @@ namespace osp { +/** + * @brief Reserves the first empty value found in topData after the index current + * + * @return The index of the reserved value, or if topData is full, the largest index in topData + */ [[nodiscard]] inline TopDataId top_reserve( ArrayView const topData, TopDataId current = 0) { @@ -57,6 +62,13 @@ namespace osp return current; } +/** + * @brief Reserves n values in topData, where n = destLast - destFirst + * and stores the reserved indices inside of the iterable object that destFirst belongs to + * + * @return The largest index that was reserved in topData, or if topData is full, + * the largest index in topData + */ template TopDataId top_reserve( ArrayView const topData, TopDataId current, @@ -81,6 +93,11 @@ TopDataId top_reserve( return current; } +/** + * @brief Using args, constructs an object of type T at the index ID inside topData + * + * @return A reference to the newly constructed value + */ template T& top_emplace(ArrayView const topData, TopDataId id, ARGS_T&& ... args) { @@ -89,6 +106,11 @@ T& top_emplace(ArrayView const topData, TopDataId id, ARGS_T&& ... ar return entt::any_cast(rData); } +/** + * @brief Assigns the value at index id of topData to the value any + * + * @return A reference to the newly assigned value + */ template T& top_assign(ArrayView const topData, TopDataId id, ANY_T&& any) { @@ -97,7 +119,9 @@ T& top_assign(ArrayView const topData, TopDataId id, ANY_T&& any) return entt::any_cast(rData); } - +/** + * @return A reference to the value at index id inside topData + */ template [[nodiscard]] T& top_get(ArrayView const topData, TopDataId const id) { From 8d011657e3547791dc325de308acf5792f83271f Mon Sep 17 00:00:00 2001 From: Ben-Bingham Date: Sat, 11 May 2024 11:10:30 -0600 Subject: [PATCH 3/5] Requested changes --- src/osp/tasks/top_session.h | 13 ++++--------- src/osp/tasks/top_utils.h | 15 ++++++++------- 2 files changed, 12 insertions(+), 16 deletions(-) diff --git a/src/osp/tasks/top_session.h b/src/osp/tasks/top_session.h index 76e38e7e..e71cd22a 100644 --- a/src/osp/tasks/top_session.h +++ b/src/osp/tasks/top_session.h @@ -49,9 +49,8 @@ * and declares an ID variable for each element that is given. * The same ID's are also stored inside of the sessions m_data member * - * @param arglist A variadic argument broken into two sections: - * Firstly: 'count' The count is an integer equal to the number of id's - * Secondly: id's Every id is a unique index into 'topData' + * @param count The number of id variables passed to the macro. + * @param ids A set of variables that will each be assigned to a unique index of topData. */ #define OSP_DECLARE_CREATE_DATA_IDS(session, topData, arglist) OSP_AUX_DCDI_A(session, topData, arglist); @@ -65,12 +64,8 @@ * @brief Retrieves a section of data within topData that was already given to a session * and maps an ID variable to each element that is retrieved. * - * Because the data was already given, the indices are stored within the session and topData does - * not need to be accessed. - * - * @param arglist A variadic argument broken into two sections: - * Firstly: 'count' The count is an integer equal to the number of id's - * Secondly: id's Every id is a unique index into 'topData' + * @param count The number of id variables passed to the macro. + * @param ids A set of variables that will each be assigned to a unique index of topData. */ #define OSP_DECLARE_GET_DATA_IDS(session, arglist) OSP_AUX_DGDI_A(session, arglist); diff --git a/src/osp/tasks/top_utils.h b/src/osp/tasks/top_utils.h index 4d0244a1..104da2ff 100644 --- a/src/osp/tasks/top_utils.h +++ b/src/osp/tasks/top_utils.h @@ -40,11 +40,12 @@ namespace osp { - + /** - * @brief Reserves the first empty value found in topData after the index current - * - * @return The index of the reserved value, or if topData is full, the largest index in topData + * @brief Reserves the first available space in topData after the indicated index. + * + * @return The index of the reserved value, or the index after the end of topData if no slots are + * available after the indicated index. */ [[nodiscard]] inline TopDataId top_reserve( ArrayView const topData, TopDataId current = 0) @@ -63,8 +64,8 @@ namespace osp } /** - * @brief Reserves n values in topData, where n = destLast - destFirst - * and stores the reserved indices inside of the iterable object that destFirst belongs to + * @brief Reserves a slot in topData for each item in the output range [destFirst, destLast), + * writing the associated indices into the range. * * @return The largest index that was reserved in topData, or if topData is full, * the largest index in topData @@ -94,7 +95,7 @@ TopDataId top_reserve( } /** - * @brief Using args, constructs an object of type T at the index ID inside topData + * @brief Constructs an object of type T at the indicated index. * * @return A reference to the newly constructed value */ From 275ffd1b4a6cf867646b0cf71e15461359a3d3f9 Mon Sep 17 00:00:00 2001 From: Ben-Bingham Date: Sat, 11 May 2024 15:56:09 -0600 Subject: [PATCH 4/5] Fixed spacing/formatting of @brief comments --- src/osp/tasks/top_session.h | 7 ++++--- src/osp/tasks/top_utils.h | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/osp/tasks/top_session.h b/src/osp/tasks/top_session.h index e71cd22a..5897507c 100644 --- a/src/osp/tasks/top_session.h +++ b/src/osp/tasks/top_session.h @@ -46,8 +46,9 @@ /** * @brief Gives the next available section of topData to a session - * and declares an ID variable for each element that is given. - * The same ID's are also stored inside of the sessions m_data member + * and declares an ID variable for each element that is given. + * + * The same ID's are also stored inside of the sessions m_data member. * * @param count The number of id variables passed to the macro. * @param ids A set of variables that will each be assigned to a unique index of topData. @@ -62,7 +63,7 @@ /** * @brief Retrieves a section of data within topData that was already given to a session - * and maps an ID variable to each element that is retrieved. + * and maps an ID variable to each element that is retrieved. * * @param count The number of id variables passed to the macro. * @param ids A set of variables that will each be assigned to a unique index of topData. diff --git a/src/osp/tasks/top_utils.h b/src/osp/tasks/top_utils.h index 104da2ff..88a8fe61 100644 --- a/src/osp/tasks/top_utils.h +++ b/src/osp/tasks/top_utils.h @@ -65,7 +65,7 @@ namespace osp /** * @brief Reserves a slot in topData for each item in the output range [destFirst, destLast), - * writing the associated indices into the range. + * writing the associated indices into the range. * * @return The largest index that was reserved in topData, or if topData is full, * the largest index in topData From 60507ebb1c5419ef1ea5ad99dd3c6c0cf99e650a Mon Sep 17 00:00:00 2001 From: Ben-Bingham Date: Sat, 11 May 2024 15:58:54 -0600 Subject: [PATCH 5/5] Changed parameter names in documentation for macros --- src/osp/tasks/top_session.h | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/osp/tasks/top_session.h b/src/osp/tasks/top_session.h index 5897507c..ecbf5281 100644 --- a/src/osp/tasks/top_session.h +++ b/src/osp/tasks/top_session.h @@ -50,8 +50,9 @@ * * The same ID's are also stored inside of the sessions m_data member. * - * @param count The number of id variables passed to the macro. - * @param ids A set of variables that will each be assigned to a unique index of topData. + * @param arglist - Made of two sections: + * count: The number of id variables passed to the macro. + * ids: A set of variables that will each be assigned to a unique index of topData. */ #define OSP_DECLARE_CREATE_DATA_IDS(session, topData, arglist) OSP_AUX_DCDI_A(session, topData, arglist); @@ -65,8 +66,9 @@ * @brief Retrieves a section of data within topData that was already given to a session * and maps an ID variable to each element that is retrieved. * - * @param count The number of id variables passed to the macro. - * @param ids A set of variables that will each be assigned to a unique index of topData. + * @param arglist - Made of two sections: + * count: The number of id variables passed to the macro. + * ids: A set of variables that will each be assigned to a unique index of topData. */ #define OSP_DECLARE_GET_DATA_IDS(session, arglist) OSP_AUX_DGDI_A(session, arglist);