Improve some comments

[ci skip]

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.

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