libyang DOC new section about handling foreign XPath in operations
diff --git a/src/libyang.h b/src/libyang.h
index dde494d..b1a0cbd 100644
--- a/src/libyang.h
+++ b/src/libyang.h
@@ -367,18 +367,11 @@
* All data nodes in data trees are connected with their schema node - libyang is not able to represent data of an
* unknown schema.
*
- * By default, the represented data are supposed to represent a full YANG datastore content. So if a schema declares
- * some mandatory nodes, despite configuration or status, the data are supposed to be present in the data tree being
- * loaded or validated. However, it is possible to specify other kinds of data (see @ref parseroptions) allowing some
- * exceptions to the validation process.
- *
- * Data validation is performed implicitly to the input data processed by the parser (\b lyd_parse_*() functions) and
- * on demand via the lyd_validate() function. The lyd_validate() is supposed to be used when a (complex or simple)
- * change is done on the data tree (via a combination of \b lyd_change_*(), \b lyd_insert*(), \b lyd_new*(),
- * lyd_unlink() and lyd_free() functions).
+ * Please, continue reading a specific subsection or go through all the subsections if you are a new user of libyang.
*
* - @subpage howtodataparsers
* - @subpage howtodatamanipulators
+ * - @subpage howtodatavalidation
* - @subpage howtodatawd
* - @subpage howtodataprinters
*
@@ -436,7 +429,7 @@
* can cause failure of various libyang functions later.
*
* Creating data is generally possible in two ways, they can be combined. You can add nodes one-by-one based on
- * the node name and/or its parent (lyd_new(), lyd_new_anyxml_*(), lyd_new_leaf(), and their output variants) or
+ * the node name and/or its parent (lyd_new(), \b lyd_new_anydata_*(), lyd_new_leaf(), and their output variants) or
* address the nodes using a simple XPath addressing (lyd_new_path()). The latter enables to create a whole path
* of nodes, requires less information about the modified data, and is generally simpler to use. The path format
* specifics can be found [here](@ref howtoxpath).
@@ -472,6 +465,63 @@
* - lyd_free()
* - lyd_free_attr()
* - lyd_free_withsiblings()
+ */
+
+/**
+ * @page howtodatavalidation Validating Data
+ *
+ * By default, the represented data are supposed to represent a full YANG datastore content. So if a schema declares
+ * some mandatory nodes, despite configuration or status, the data are supposed to be present in the data tree being
+ * loaded or validated. However, it is possible to specify other kinds of data (see @ref parseroptions) allowing some
+ * exceptions to the validation process.
+ *
+ * Data validation is performed implicitly to the input data processed by the parser (\b lyd_parse_*() functions) and
+ * on demand via the lyd_validate() function. The lyd_validate() is supposed to be used when a (complex or simple)
+ * change is done on the data tree (via a combination of \b lyd_change_*(), \b lyd_insert*(), \b lyd_new*(),
+ * lyd_unlink() and lyd_free() functions).
+ *
+ * Must And When Conditions Accessible Tree
+ * ----------------------------------------
+ *
+ * In YANG 1.1, there can be \b must and/or \b when expressions in RPC/action input or output, or in notifications that
+ * require access to the configuration datastore and/or state data. Normally, when working with any of the aforementioned
+ * data trees, they must contain only the RPC/action/notification itself, without any additional configuration or state
+ * data. So how can then these conditions be verified during validation?
+ *
+ * There is an option to pass this additional data tree to all the functions that perform \b must and \b when condition
+ * checking (\b lyd_parse_*() and lyd_validate()). Also, there is a flag #LYS_XPATH_DEP of \b struct lys_node that
+ * marks schema nodes that include conditions that require foreign nodes (outside their subtree) for their evaluation.
+ * The subtree root is always the particular operation data node (for RPC it is the RPC data node and all
+ * the input or output nodes as its children and similarly for action and notification). Note that for action and
+ * not-top-level notification this means that all their parents are not considered as belonging to their subtree even though
+ * they are included in their data tree and must be present for the operation validation to pass. The reason for this is that if
+ * there are any lists in those parents, we cannot know if there are not some other instances of them in the standard
+ * data tree in addition to the one used in the action/notification invocation.
+ *
+ * There were 2 ways of using this mechanism envisioned (explained below), but you can combine or modify them.
+ *
+ * ### Fine-grained Data Retrieval ###
+ *
+ * This approach is recommended when you do not maintain a full configuration data tree with state data at all times.
+ *
+ * Firstly, you should somehow learn that the operation data tree you are currently working with includes some schema
+ * node instances that have conditions that require foreign data. You can either know this about every operation beforehand
+ * or you go through all the schema nodes looking for the flag #LYS_XPATH_DEP. Then you should use lys_node_xpath_atomize()
+ * to retrieve all XPath condition dependencies (in the form of schema nodes) outside the operation subtree. You will likely
+ * want to use the flag #LYXP_NO_LOCAL to get rid of all the nodes from inside the subtree (you should already have those).
+ * The last thing to do is to build a data tree that includes at least all the instances of the nodes obtained from lys_node_xpath_atomize()
+ * (it will be expected). Then you pass this tree to the validation and it should now have access to all the nodes that
+ * can potentially affect the XPath evaluation and no other.
+ *
+ * ### Maintaining Configuration And State Data Tree ###
+ *
+ * If you have a full data tree with state data available for the validation process then it is quite simple (compared
+ * to the first approach). You can simply always pass it to validation of these operations and in cases it is not required
+ * (no nodes with conditions traversing foreign nodes) only a negligible amount of redundant work is performed and you can
+ * skip the process of learning whether it is required or not.
+ *
+ * Functions List
+ * --------------
* - lyd_validate()
*/