yin parser CHANGE update documentation comments and add references
diff --git a/src/parser_yin.c b/src/parser_yin.c
index 59fa8d9..08b63e7 100644
--- a/src/parser_yin.c
+++ b/src/parser_yin.c
@@ -197,7 +197,7 @@
* @brief Parse yin argument.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Array of attributes.
+ * @param[in] attrs ([Sized array](@ref sizedarrays)) of attributes.
* @param[in,out] data Data to read from.
* @param[in] arg_type Type of argument that is expected in parsed element (use YIN_ARG_NONE for elements without special argument).
* @param[out] arg_val Where value of argument should be stored. Can be NULL if arg_type is specified as YIN_ARG_NONE.
@@ -283,7 +283,17 @@
return NULL;
}
-LY_ERR
+/**
+ * @brief Helper function to check mandatory constraint of subelement.
+ *
+ * @param[in,out] ctx Yin parser context for logging and to store current state.
+ * @param[in] subelem_info Array of information about subelements.
+ * @param[in] subelem_info_size Size of subelem_info array.
+ * @param[in] current_element Identification of element that is currently being parsed, used for logging.
+ *
+ * @return LY_ERR values.
+ */
+static LY_ERR
yin_check_subelem_mandatory_constraint(struct yin_parser_ctx *ctx, struct yin_subelement *subelem_info,
signed char subelem_info_size, enum yang_keyword current_element)
{
@@ -299,7 +309,18 @@
return LY_SUCCESS;
}
-LY_ERR
+/**
+ * @brief Helper function to check "first" constraint of subelement.
+ *
+ * @param[in,out] ctx Yin parser context for logging and to store current state.
+ * @param[in] subelem_info Array of information about subelements.
+ * @param[in] subelem_info_size Size of subelem_info array.
+ * @param[in] current_element Identification of element that is currently being parsed, used for logging.
+ * @param[in] exp_first Record in subelem_info array that is expected to be defined as first subelement.
+ *
+ * @return LY_ERR values.
+ */
+static LY_ERR
yin_check_subelem_first_constraint(struct yin_parser_ctx *ctx, struct yin_subelement *subelem_info,
signed char subelem_info_size, enum yang_keyword current_element, struct yin_subelement *exp_first)
{
@@ -315,7 +336,15 @@
}
/* TODO add something like ifdef NDEBUG around this function, this is supposed to be checked only in debug mode */
-bool
+/**
+ * @brief Helper function to check if array of information about subelements is in ascending order.
+ *
+ * @param[in] subelem_info Array of information about subelements.
+ * @param[in] subelem_info_size Size of subelem_info array.
+ *
+ * @return True iff subelem_info array is in ascending order, False otherwise.
+ */
+static bool
is_ordered(struct yin_subelement *subelem_info, signed char subelem_info_size)
{
enum yang_keyword current = YANG_NONE; /* 0 (minimal value) */
@@ -335,7 +364,7 @@
* for example prefix or namespace element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Attributes of current element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of current element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in] kw Type of current element.
* @param[out] value Where value of attribute should be stored.
@@ -360,7 +389,7 @@
* more instances, such as base or if-feature.
*
* @param[in,out] ctx YIN parser context for logging and to store current state.
- * @param[in] attrs Attributes of current element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of current element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in] kw Type of current element.
* @param[out] values Parsed values to add to.
@@ -388,9 +417,10 @@
* text element as child
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] args Sized array of arguments of current element.
* @param[in,out] data Data to read from.
+ * @param[in] Type of element can be se to YANG_ORGANIZATION or YANG_CONTACT or YANG_DESCRIPTION or YANG_REFERENCE.
* @param[out] value Where the content of meta element should be stored.
+ * @param[in,out] exts Extension instance to add to.
*
* @return LY_ERR values.
*/
@@ -491,7 +521,7 @@
* @brief Parse belongs-to element.
*
* @param[in] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Array of attributes of belongs-to element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of current element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[out] submod Structure of submodule that is being parsed.
* @param[in,out] exts Extension instances to add to.
diff --git a/src/parser_yin.h b/src/parser_yin.h
index 32060a5..82c4e9b 100644
--- a/src/parser_yin.h
+++ b/src/parser_yin.h
@@ -58,7 +58,7 @@
struct yin_parser_ctx {
struct lyxml_context xml_ctx; /**< context for xml parser */
- uint8_t mod_version; /**< module's version */
+ uint8_t mod_version; /**< module's version */
};
/* flags to encode cardinality of subelement */
@@ -120,7 +120,7 @@
* @brief Parse yang-version element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Attributes of when element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of yang-version element.
* @param[in] data Data to read from, always moved to currently handled character.
* @param[out] version Storage for the parsed information.
* @param[in,out] exts Extension instance to add to.
@@ -134,7 +134,7 @@
* @brief Parse import element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Sized array of attributes of import element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of import element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in,out] mod Structure of module that is being parsed.
*
@@ -161,7 +161,7 @@
* @brief Parse status element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Atributes of status element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of status element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in,out] flags Flags to add to.
* @param[in,out] exts Extension instances to add to.
@@ -175,17 +175,18 @@
* @brief Parse when element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Attributes of when element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of when element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[out] when_p When pointer to parse to.
*/
-LY_ERR yin_parse_when(struct yin_parser_ctx *ctx, struct yin_arg_record *attrs, const char **data, struct lysp_when **when_p);
+LY_ERR yin_parse_when(struct yin_parser_ctx *ctx, struct yin_arg_record *attrs, const char **data,
+ struct lysp_when **when_p);
/**
* @brief Parse revision date element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Sized array of attributes of revision-date element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of revision-date element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in,out] rev Array to store the parsed value in.
* @param[in,out] exts Extension instances to add to.
@@ -196,11 +197,11 @@
char *rev, struct lysp_ext_instance **exts);
/**
- * @brief Load all attributes from current element. Caller is supposed to free attrs array.
+ * @brief load all attributes of element into ([sized array](@ref sizedarrays)). Caller is suposed to free the array.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
* @param[in,out] data Data to read from, always moved to currently handled character.
- * @param[out] attrs Sized array of attributes.
+ * @param[out] attrs ([Sized array](@ref sizedarrays)) of attributes.
*
* @return LY_ERR values.
*/
@@ -210,7 +211,7 @@
* @brief Parse yin-elemenet element.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Sized array of element attributes.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of yin-element element.
* @param[in,out] data Data to read from, always moved to currently handled position.
* @param[in,out] flags Flags to add to.
* @prama[in,out] exts Extension instance to add to.
@@ -224,7 +225,7 @@
* @brief Parse argument element.
*
* @param[in,out] xml_ctx Xml context.
- * @param[in] attrs Attributes of this element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of argument element.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in,out] arg_meta Meta information about destionation af prased data.
* @param[in,out] exts Extension instance to add to.
@@ -238,7 +239,7 @@
* @brief Parse the extension statement.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Attributes of extension element.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of extension element.
* @param[in,out] data Data to read from.
* @param[in,out] extensions Extensions to add to.
*
@@ -251,7 +252,7 @@
* @brief Parse instance of extension.
*
* @param[in,out] ctx Yin parser context for logging and to store current state.
- * @param[in] attrs Sized array of attributes.
+ * @param[in] attrs [Sized array](@ref sizedarrays) of attributes of extension instance.
* @param[in,out] data Data to read from, always moved to currently handled character.
* @param[in] ext_name Name of the extension element.
* @param[in] ext_name_len Length of extension name.