From 6cf1530eeddd66d7d9f02f30a2b70abbcde52145 Mon Sep 17 00:00:00 2001 From: Joao Paulo Magalhaes Date: Thu, 4 Apr 2024 19:27:29 +0100 Subject: [PATCH] Improve some comments [ci skip] --- changelog/current.md | 4 ++-- src/c4/yml/node.hpp | 40 ++++++++++++++++++++++------------------ 2 files changed, 24 insertions(+), 20 deletions(-) diff --git a/changelog/current.md b/changelog/current.md index 587333f0e..099f3d067 100644 --- a/changelog/current.md +++ b/changelog/current.md @@ -23,7 +23,7 @@ Fix major error handling problem reported in [#389](https://github.com/biojppm/r * callback instead of directly raising an exception. */ ConstNodeRef at(csubstr key) const; /** Likewise, but return a seed node when the key is not found */ - ConstNodeRef at(csubstr key); + NodeRef at(csubstr key); /** Get a child by position, with error checking; complexity is * O(pos). @@ -36,7 +36,7 @@ Fix major error handling problem reported in [#389](https://github.com/biojppm/r * callback instead of directly raising an exception. */ ConstNodeRef at(size_t pos) const; /** Likewise, but return a seed node when pos is not found */ - ConstNodeRef at(csubstr key); + NodeRef at(csubstr key); ``` - Added macros and respective cmake options to control error handling: - `RYML_USE_ASSERT` - enable assertions regardless of build type. This is disabled by default. diff --git a/src/c4/yml/node.hpp b/src/c4/yml/node.hpp index e1d234171..07d9870af 100644 --- a/src/c4/yml/node.hpp +++ b/src/c4/yml/node.hpp @@ -424,8 +424,12 @@ struct RoNodeMethods /** @name at * * These functions are the analogue to operator[], with the - * difference that they */ - /** @{ */ + * difference that they emit an error instead of an + * assertion. That is, if any of the pre or post conditions is + * violated, an error is always emitted (resulting in a call to + * the error callback). + * + * @{ */ /** Find child by key; complexity is O(num_children). * @@ -440,14 +444,14 @@ struct RoNodeMethods * to read from the tree. * * @warning This method will call the error callback (regardless - * of build type) whenever any of the following preconditions is - * violated: a) the object is valid (points at a tree and a node), - * b) the calling object must be readable (must not be in seed - * state), c) the calling object must be pointing at a MAP - * node. The preconditions are similar to the non-const - * operator[](csubstr), but instead of using assertions, this - * function directly checks those conditions and calls the error - * callback if any of the checks fail. + * of build type or of the value of RYML_USE_ASSERT) whenever any + * of the following preconditions is violated: a) the object is + * valid (points at a tree and a node), b) the calling object must + * be readable (must not be in seed state), c) the calling object + * must be pointing at a MAP node. The preconditions are similar + * to the non-const operator[](csubstr), but instead of using + * assertions, this function directly checks those conditions and + * calls the error callback if any of the checks fail. * * @note since it is valid behavior for the returned node to be in * seed state, the error callback is not invoked when this @@ -476,14 +480,14 @@ struct RoNodeMethods * from the tree. * * @warning This method will call the error callback (regardless - * of build type) whenever any of the following preconditions is - * violated: a) the object is valid (points at a tree and a node), - * b) the calling object must be readable (must not be in seed - * state), c) the calling object must be pointing at a MAP - * node. The preconditions are similar to the non-const - * operator[](size_t), but instead of using assertions, this - * function directly checks those conditions and calls the error - * callback if any of the checks fail. + * of build type or of the value of RYML_USE_ASSERT) whenever any + * of the following preconditions is violated: a) the object is + * valid (points at a tree and a node), b) the calling object must + * be readable (must not be in seed state), c) the calling object + * must be pointing at a MAP node. The preconditions are similar + * to the non-const operator[](size_t), but instead of using + * assertions, this function directly checks those conditions and + * calls the error callback if any of the checks fail. * * @note since it is valid behavior for the returned node to be in * seed state, the error callback is not invoked when this