tree data DOC warn about previous siblings for lyd_new_path
diff --git a/src/tree_data.h b/src/tree_data.h
index ca9bf0a..4b3118d 100644
--- a/src/tree_data.h
+++ b/src/tree_data.h
@@ -967,9 +967,11 @@
* and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path
* and @p value is set, the predicate is preferred.
*
- * @param[in] parent Data parent to add to/modify, can be NULL.
+ * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
+ * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
+ * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
* @param[in] ctx libyang context, must be set if @p parent is NULL.
- * @param[in] path Path to create (TODO ref path).
+ * @param[in] path [Path](@ref howtoXPath) to create.
* @param[in] value Value of the new leaf/leaf-list. For other node types, it is ignored.
* @param[in] options Bitmask of options, see @ref pathoptions.
* @param[out] node Optional first created node.
@@ -985,9 +987,11 @@
* and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path
* and @p value is set, the predicate is preferred.
*
- * @param[in] parent Data parent to add to/modify, can be NULL.
+ * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
+ * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
+ * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
* @param[in] ctx libyang context, must be set if @p parent is NULL.
- * @param[in] path Path to create (TODO ref path).
+ * @param[in] path [Path](@ref howtoXPath) to create.
* @param[in] value Value of the new leaf/leaf-list/anyxml/anydata. For other node types, it is ignored.
* @param[in] value_type Anyxml/anydata node @p value type.
* @param[in] options Bitmask of options, see @ref pathoptions.
@@ -1004,9 +1008,11 @@
* and @p value is ignored. Also, if a leaf-list is being created and both a predicate is defined in @p path
* and @p value is set, the predicate is preferred.
*
- * @param[in] parent Data parent to add to/modify, can be NULL.
+ * @param[in] parent Data parent to add to/modify, can be NULL. Note that in case a first top-level sibling is used,
+ * it may no longer be first if @p path is absolute and starts with a non-existing top-level node inserted
+ * before @p parent. Use ::lyd_first_sibling() to adjust @p parent in these cases.
* @param[in] ctx libyang context, must be set if @p parent is NULL.
- * @param[in] path Path to create (TODO ref path).
+ * @param[in] path [Path](@ref howtoXPath) to create.
* @param[in] value Value of the new leaf/leaf-list/anyxml/anydata. For other node types, it is ignored.
* @param[in] value_type Anyxml/anydata node @p value type.
* @param[in] options Bitmask of options, see @ref pathoptions.