doc UPDATE updates and improvements
diff --git a/doc/transition.dox b/doc/transition.dox
index 2e086df..0fb36cd 100644
--- a/doc/transition.dox
+++ b/doc/transition.dox
@@ -37,7 +37,6 @@
* libyang 1.x | libyang 2.0 | Notes
* :-------------------------|:-------------------------------------|:-------------------------------------------------------
* - | ::ly_err_last() | New API for handling errors.
- * - | ::ly_errcode() | ^
* ly_verb_dbg() | ::ly_log_dbg_groups() | Rename to align with the names of the accepted values.
* ly_verb() | ::ly_log_level() | ^
*
diff --git a/src/context.h b/src/context.h
index 9f1b8e6..31f41b9 100644
--- a/src/context.h
+++ b/src/context.h
@@ -202,13 +202,11 @@
'require-instance false;'. It also enables usage of
[lyd_leafref_get_links](@ref lyd_leafref_get_links) and
[lyd_leafref_link_node_tree](@ref lyd_leafref_link_node_tree) APIs. */
-#define LY_CTX_BUILTIN_PLUGINS_ONLY 0x0800 /**< By default, context loads all available built-in plugins and extensions. This
- options prohibits loading of built-in non-YANG plugin types and extensions (ipv4-address,
- ipv6-address, etc.). Instead the value is processed by built-in YANG plugins (usually string)
- with all its behavioral implications as hex-string comparison becoming case-sensitive.
- Change of this flag during the lifetime of context is not fully supported. Once the non-YANG
- plugins or extensions are loaded during context creation, they will be used regardless of this
- flag. Therefore it is recommended to set this flag during the first context creation. */
+#define LY_CTX_BUILTIN_PLUGINS_ONLY 0x0800 /**< By default, context uses all available plugins for types and extensions,
+ both included and external. This options prevents all included plugins to be
+ loaded except for built-in YANG types so all derived types will use these and
+ for all purposes behave as the base type. The option can be used for cases when
+ invalid data needs to be stored in YANG node values. */
/** @} contextoptions */
diff --git a/src/log.h b/src/log.h
index 49262c7..85f2ac6 100644
--- a/src/log.h
+++ b/src/log.h
@@ -175,10 +175,6 @@
/**
* @brief Logger callback.
*
- * !IMPORTANT! If an error has a specific error-app-tag defined in the model, it will NOT be set
- * at the time of calling this callback. It will be set right after, so to retrieve it
- * it must be checked afterwards with ::ly_errapptag().
- *
* @param[in] level Log level of the message.
* @param[in] msg Message.
* @param[in] data_path Optional data path of the related node.
@@ -223,13 +219,6 @@
*
* To print a specific error information via libyang logger, there is ::ly_err_print().
*
- * To simplify access to the last error record in the context, there is a set of functions returning important error information.
- * - ::ly_errapptag()
- * - ::ly_errcode()
- * - ::ly_vecode()
- * - ::ly_errmsg()
- * - ::ly_errpath()
- *
* \note API for this group of functions is described in the [error information module](@ref errors).
*/
diff --git a/src/parser_data.h b/src/parser_data.h
index e782b47..e1a6d11 100644
--- a/src/parser_data.h
+++ b/src/parser_data.h
@@ -134,21 +134,21 @@
* - when statements on existing nodes are evaluated, if not satisfied, a validation error is raised,
* - invalid multiple data instances/data from several cases cause a validation error,
* - implicit nodes (NP containers and default values) are added.
- * - Validations based on leaf/leaf-list types restriction is being done regardless of setting LYD_PARSE_ONLY
* @{
*/
/* note: keep the lower 16bits free for use by LYD_VALIDATE_ flags. They are not supposed to be combined together,
* but since they are used (as a separate parameter) together in some functions, we want to keep them in a separated
* range to be able detect that the caller put wrong flags into the parser/validate options parameter. */
-#define LYD_PARSE_ONLY 0x010000 /**< Data will be only parsed and no validation will be performed. When statements
- are kept unevaluated, union types may not be fully resolved, and
- default values are not added (only the ones parsed are present). */
+#define LYD_PARSE_ONLY 0x010000 /**< Data will be only parsed and no data validation will be performed but
+ type value restrictions will be checked (unlike ::LYD_PARSE_STORE_ONLY).
+ When statements are kept unevaluated, union types may not be fully
+ resolved, and default values are not added (only the ones parsed are
+ present). */
#define LYD_PARSE_STRICT 0x020000 /**< Instead of silently ignoring data without schema definition raise an error.
Do not combine with ::LYD_PARSE_OPAQ (except for ::LYD_LYB). */
#define LYD_PARSE_OPAQ 0x040000 /**< Instead of silently ignoring data without definition, parse them into
an opaq node. Do not combine with ::LYD_PARSE_STRICT (except for ::LYD_LYB). */
#define LYD_PARSE_NO_STATE 0x080000 /**< Forbid state data in the parsed data. Usually used with ::LYD_VALIDATE_NO_STATE. */
-
#define LYD_PARSE_LYB_MOD_UPDATE 0x100000 /**< Only for LYB format, allow parsing data printed using a specific module
revision to be loaded even with a module with the same name but newer
revision. */
@@ -172,8 +172,10 @@
#define LYD_PARSE_NO_NEW 0x1000000 /**< Do not set ::LYD_NEW (non-validated node flag) for any nodes. Use
when parsing validated data to skip some validation tasks and modify
some validation behavior (auto-deletion of cases). */
-#define LYD_PARSE_STORE_ONLY 0x2000000 /**< Perform only storing operation, no validation based on leaf/leaf-list type
- restrictions will be performed. */
+#define LYD_PARSE_STORE_ONLY 0x2000000 /**< Similar to ::LYD_PARSE_ONLY but even type value restrictions will not
+ be checked (length, range, pattern, ...) and if a value can be stored,
+ it is. Calling separate validation on these data always checks all the
+ restrictions as well. */
#define LYD_PARSE_OPTS_MASK 0xFFFF0000 /**< Mask for all the LYD_PARSE_ options. */
diff --git a/src/plugins_exts.h b/src/plugins_exts.h
index 78c6e6f..de4c9f7 100644
--- a/src/plugins_exts.h
+++ b/src/plugins_exts.h
@@ -575,7 +575,7 @@
* @param[in] cctx Optional compile context to generate the path from.
* @param[in] ext Compiled extension instance.
* @param[in] level Log message level (error, warning, etc.)
- * @param[in] err_no Error type code.
+ * @param[in] err Error type code.
* @param[in] format Format string to print.
*/
LIBYANG_API_DECL void lyplg_ext_compile_log(const struct lysc_ctx *cctx, const struct lysc_ext_instance *ext,
@@ -587,7 +587,7 @@
* @param[in] path Log error schema path to use.
* @param[in] ext Compiled extension instance.
* @param[in] level Log message level (error, warning, etc.)
- * @param[in] err_no Error type code.
+ * @param[in] err Error type code.
* @param[in] format Format string to print.
*/
LIBYANG_API_DECL void lyplg_ext_compile_log_path(const char *path, const struct lysc_ext_instance *ext,
diff --git a/src/plugins_types.h b/src/plugins_types.h
index 184393c..8598c5d 100644
--- a/src/plugins_types.h
+++ b/src/plugins_types.h
@@ -1292,7 +1292,7 @@
* @param[in] node Context node.
* @param[in] value Target value.
* @param[in] tree Full data tree to search in.
- * @param[out] target Pointer to set of target nodes, optional.
+ * @param[out] targets Pointer to set of target nodes, optional.
* @param[out] errmsg Error message in case of error.
* @return LY_ERR value.
*/
diff --git a/src/tree_data.h b/src/tree_data.h
index 9084f8e..ba33f26 100644
--- a/src/tree_data.h
+++ b/src/tree_data.h
@@ -1248,7 +1248,7 @@
/**
* @ingroup datatree
- * @defgroup newvalueoptions New value creation options
+ * @defgroup newvaloptions New value creation options
*
* Various options to change lyd_new_*() behavior. The LYD_NEW_VAL* can be used within any API, others
* are API specific
@@ -1257,11 +1257,13 @@
* - the input data nodes or RPC/Action is taken into account
* - the value is being validated with all possible validations, which doesn't require existence of any other data nodes
* - the input value is expected to be in JSON format
+ * - RPC output schema children are completely ignored in all modules. Input is searched and nodes created normally.
+ *
+ * Default behavior specific for lyd_new_path*() functions:
* - if the target node already exists (and is not default), an error is returned.
* - the whole path to the target node is created (with any missing parents) if necessary.
- * - RPC output schema children are completely ignored in all modules. Input is searched and nodes created normally.
* - during creation of new metadata, the nodes will have default flag set
- * - value is copied and stored internally during any node creation
+ * - string value is copied and stored internally during any node creation
* @{
*/
@@ -1284,7 +1286,7 @@
#define LYD_NEW_PATH_WITH_OPAQ 0x80 /**< Consider opaque nodes normally when searching for existing nodes. */
#define LYD_NEW_ANY_USE_VALUE 0x100 /**< Whether to use dynamic @p value or make a copy. */
-/** @} newvalueoptions */
+/** @} newvaloptions */
/**
* @brief Create a new list node in the data tree.
@@ -1292,11 +1294,11 @@
* @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
* @param[in] module Module of the node being created. If NULL, @p parent module will be used.
* @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node Optional created node.
* @param[in] ... Ordered key values of the new list instance, all must be set. In case of an instance-identifier
* or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for key-less lists.
- * In case of format set to LY_FORMAT_LYB, every key value must be followed by its length.
+ * In case options include ::LYD_NEW_VAL_BIN, every key value must be followed by its length.
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lyd_new_list(struct lyd_node *parent, const struct lys_module *module, const char *name,
@@ -1310,11 +1312,11 @@
*
* @param[in] ext Extension instance where the list node being created is defined.
* @param[in] name Schema node name of the new data node. The node must be #LYS_LIST.
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node The created node.
* @param[in] ... Ordered key values of the new list instance, all must be set. In case of an instance-identifier
* or identityref value, the JSON format is expected (module names instead of prefixes). No keys are expected for key-less lists.
- * In case of format set to LY_FORMAT_LYB, every key value must be followed by its length.
+ * In case options include ::LYD_NEW_VAL_BIN, every key value must be followed by its length.
* @return LY_ERR value.
*/
LIBYANG_API_DECL LY_ERR lyd_new_ext_list(const struct lysc_ext_instance *ext, const char *name, uint32_t options,
@@ -1329,7 +1331,7 @@
* @param[in] keys All key values predicate in the form of "[key1='val1'][key2='val2']...", they do not have to be ordered.
* In case of an instance-identifier or identityref value, the JSON format is expected (module names instead of prefixes).
* Use NULL or string of length 0 in case of key-less list.
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node Optional created node.
* @return LY_ERR value.
*/
@@ -1377,8 +1379,8 @@
* @param[in] parent Parent node for the node being created. NULL in case of creating a top level element.
* @param[in] module Module of the node being created. If NULL, @p parent module will be used.
* @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
- * @param[in] value The value of the node in @p format.
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] value Value of the node in JSON format unless changed by @p options.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node Optional created node.
* @return LY_ERR value.
*/
@@ -1392,9 +1394,8 @@
* @param[in] module Module of the node being created. If NULL, @p parent module will be used.
* @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
* @param[in] value Binary value of the node. To learn what exactly is expected see @ref howtoDataLYB.
- * @param[in] value The value of the node in @p format.
* @param[in] value_len Length of @p value.
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node Optional created node.
* @return LY_ERR value.
*/
@@ -1409,10 +1410,9 @@
*
* @param[in] ext Extension instance where the term node being created is defined.
* @param[in] name Schema node name of the new data node. The node can be #LYS_LEAF or #LYS_LEAFLIST.
- * @param[in] val_str String form of the value of the node being created. In case of an instance-identifier or identityref
- * @param[in] value The value of the node in @p format. In case of an instance-identifier or identityref value,
- * the JSON format is expected (module names instead of prefixes).
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] value Value of the node in JSON format unless changed by @p options.
+ * @param[in] value_len Length of @p value.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node The created node.
* @return LY_ERR value.
*/
@@ -1454,16 +1454,16 @@
uint32_t options, LYD_ANYDATA_VALUETYPE value_type, struct lyd_node **node);
/**
- * @brief Create new metadata.
+ * @brief Create a new metadata.
*
- * @param[in] ctx libyang context,
+ * @param[in] ctx libyang context.
* @param[in] parent Optional parent node for the metadata being created. Must be set if @p meta is NULL.
* @param[in] module Module of the metadata being created. If NULL, @p name must include module name as the prefix.
* @param[in] name Annotation name of the new metadata. It can include the annotation module as the prefix.
- * If the prefix is specified it is always used but if not specified, @p module must be set.
+ * If the prefix is specified it is always used but if not specified, @p module must be set.
* @param[in] val_str String form of the value of the metadata. In case of an instance-identifier or identityref
* value, the JSON format is expected (module names instead of prefixes).
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] meta Optional created metadata. Must be set if @p parent is NULL.
* @return LY_ERR value.
*/
@@ -1475,7 +1475,7 @@
*
* @param[in] ctx libyang context.
* @param[in] parent Optional parent node for the metadata being created. Must be set if @p meta is NULL.
- * @param[in] options Bitmask of options, see @ref newvalueoptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[in] attr Opaque node attribute to parse into metadata.
* @param[out] meta Optional created metadata. Must be set if @p parent is NULL.
* @return LY_SUCCESS on success.
@@ -1565,8 +1565,7 @@
* 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](@ref howtoXPath) to create.
- * @param[in] value String value of the new leaf/leaf-list. If it varies based on the format, ::LY_VALUE_JSON is expected.
- * For other node types, it should be NULL.
+ * @param[in] value String value of the new leaf/leaf-list in JSON format. For other node types it should be NULL.
* @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node Optional first created node.
* @return LY_SUCCESS on success.
@@ -1620,7 +1619,7 @@
* @param[in] ext Extension instance where the node being created is defined.
* @param[in] path [Path](@ref howtoXPath) to create.
* @param[in] value Value of the new leaf/leaf-list. For other node types, it should be NULL.
- * @param[in] options Bitmask of options, see @ref nevaloptions.
+ * @param[in] options Bitmask of options, see @ref newvaloptions.
* @param[out] node Optional first created node.
* @return LY_SUCCESS on success.
* @return LY_EEXIST if the final node to create exists (unless ::LYD_NEW_PATH_UPDATE is used).
diff --git a/src/tree_data_new.c b/src/tree_data_new.c
index 7a965a3..4051aab 100644
--- a/src/tree_data_new.c
+++ b/src/tree_data_new.c
@@ -4,7 +4,7 @@
* @author Michal Vasko <mvasko@cesnet.cz>
* @brief Data tree new functions
*
- * Copyright (c) 2015 - 2022 CESNET, z.s.p.o.
+ * Copyright (c) 2015 - 2024 CESNET, z.s.p.o.
*
* This source code is licensed under BSD 3-Clause License (the "License").
* You may not use this file except in compliance with the License.