C-style comments

This commit is contained in:
Olof hagsand 2023-08-09 18:47:40 +02:00
parent 40621f292b
commit cdc305ed2f
3 changed files with 94 additions and 61 deletions

View file

@ -82,6 +82,7 @@
/*! Translate from symbolic database name to actual filename in file-system
*
* @param[in] th text handle handle
* @param[in] db Symbolic database name, eg "candidate", "running"
* @param[out] filename Filename. Unallocate after use with free()
@ -122,6 +123,7 @@ xmldb_db2file(clicon_handle h,
}
/*! Connect to a datastore plugin, allocate resources to be used in API calls
*
* @param[in] h Clicon handle
* @retval 0 OK
* @retval -1 Error
@ -133,6 +135,7 @@ xmldb_connect(clicon_handle h)
}
/*! Disconnect from a datastore plugin and deallocate resources
*
* @param[in] handle Disconect and deallocate from this handle
* @retval 0 OK
* @retval -1 Error
@ -163,11 +166,12 @@ xmldb_disconnect(clicon_handle h)
}
/*! Copy database from db1 to db2
*
* @param[in] h Clicon handle
* @param[in] from Source database
* @param[in] to Destination database
* @retval -1 Error
* @retval 0 OK
* @retval 0 OK
* @retval -1 Error
*/
int
xmldb_copy(clicon_handle h,
@ -240,11 +244,12 @@ xmldb_copy(clicon_handle h,
}
/*! Lock database
*
* @param[in] h Clicon handle
* @param[in] db Database
* @param[in] id Session id
* @retval -1 Error
* @retval 0 OK
* @retval 0 OK
* @retval -1 Error
*/
int
xmldb_lock(clicon_handle h,
@ -264,10 +269,11 @@ xmldb_lock(clicon_handle h,
}
/*! Unlock database
*
* @param[in] h Clicon handle
* @param[in] db Database
* @retval -1 Error
* @retval 0 OK
* @retval 0 OK
* @retval -1 Error
* Assume all sanity checks have been made
*/
int
@ -285,10 +291,11 @@ xmldb_unlock(clicon_handle h,
}
/*! Unlock all databases locked by session-id (eg process dies)
* @param[in] h Clicon handle
* @param[in] id Session id
* @retval -1 Error
* @retval 0 OK
*
* @param[in] h Clicon handle
* @param[in] id Session id
* @retval 0 OK
* @retval -1 Error
*/
int
xmldb_unlock_all(clicon_handle h,
@ -320,12 +327,13 @@ xmldb_unlock_all(clicon_handle h,
}
/*! Check if database is locked
*
* @param[in] h Clicon handle
* @param[in] db Database
* @retval -1 Error
* @retval 0 Not locked
* @retval >0 Session id of locker
*/
* @retval 0 Not locked
* @retval -1 Error
*/
uint32_t
xmldb_islocked(clicon_handle h,
const char *db)
@ -338,11 +346,12 @@ xmldb_islocked(clicon_handle h,
}
/*! Get timestamp of when database was locked
*
* @param[in] h Clicon handle
* @param[in] db Database
* @param[out] tv Timestamp
* @retval -1 No timestamp / not locked
* @retval 0 OK
* @retval -1 No timestamp / not locked
*/
int
xmldb_lock_timestamp(clicon_handle h,
@ -358,11 +367,12 @@ xmldb_lock_timestamp(clicon_handle h,
}
/*! Check if db exists or is empty
*
* @param[in] h Clicon handle
* @param[in] db Database
* @retval -1 Error
* @retval 0 No it does not exist
* @retval 1 Yes it exists
* @retval 1 Yes it exists
* @retval 0 No it does not exist
* @retval -1 Error
* @note An empty datastore is treated as not existent so that a backend after dropping priviliges can re-create it
*/
int
@ -392,10 +402,11 @@ xmldb_exists(clicon_handle h,
}
/*! Clear database cache if any for mem/size optimization only, not file itself
*
* @param[in] h Clicon handle
* @param[in] db Database
* @retval -1 Error
* @retval 0 OK
* @retval 0 OK
* @retval -1 Error
*/
int
xmldb_clear(clicon_handle h,
@ -414,10 +425,12 @@ xmldb_clear(clicon_handle h,
}
/*! Delete database, clear cache if any. Remove file
*
* @param[in] h Clicon handle
* @param[in] db Database
* @retval -1 Error
* @retval 0 OK
* @retval 0 OK
* @retval -1 Error
* @note Datastore is not actually deleted so that a backend after dropping priviliges can re-create it
*/
int
@ -446,10 +459,11 @@ xmldb_delete(clicon_handle h,
}
/*! Create a database. Open database for writing.
*
* @param[in] h Clicon handle
* @param[in] db Database
* @retval 0 OK
* @retval -1 Error
* @retval 0 OK
* @retval -1 Error
*/
int
xmldb_create(clicon_handle h,
@ -484,6 +498,7 @@ xmldb_create(clicon_handle h,
}
/*! Create an XML database. If it exists already, delete it before creating
*
* Utility function.
* @param[in] h Clixon handle
* @param[in] db Symbolic database name, eg "candidate", "running"
@ -504,6 +519,7 @@ xmldb_db_reset(clicon_handle h,
}
/*! Get datastore XML cache
*
* @param[in] h Clicon handle
* @param[in] db Database name
* @retval xml XML cached tree or NULL
@ -520,11 +536,12 @@ xmldb_cache_get(clicon_handle h,
}
/*! Get modified flag from datastore
*
* @param[in] h Clicon handle
* @param[in] db Database name
* @retval -1 Error (datastore does not exist)
* @retval 0 Db is not modified
* @retval 1 Db is modified
* @retval 0 Db is not modified
* @retval -1 Error (datastore does not exist)
* @note This only makes sense for "candidate", see RFC 6241 Sec 7.5
* @note This only works if db cache is used,...
*/
@ -542,11 +559,12 @@ xmldb_modified_get(clicon_handle h,
}
/*! Get empty flag from datastore (the datastore was empty ON LOAD)
*
* @param[in] h Clicon handle
* @param[in] db Database name
* @retval -1 Error (datastore does not exist)
* @retval 0 Db was not empty on load
* @retval 1 Db was empty on load
* @retval 0 Db was not empty on load
* @retval -1 Error (datastore does not exist)
*/
int
xmldb_empty_get(clicon_handle h,
@ -562,11 +580,12 @@ xmldb_empty_get(clicon_handle h,
}
/*! Set modified flag from datastore
*
* @param[in] h Clicon handle
* @param[in] db Database name
* @param[in] value 0 or 1
* @retval -1 Error (datastore does not exist)
* @retval 0 OK
* @retval -1 Error (datastore does not exist)
* @note This only makes sense for "candidate", see RFC 6241 Sec 7.5
* @note This only works if db cache is used,...
*/
@ -615,12 +634,13 @@ xmldb_print(clicon_handle h,
}
/*! Rename an XML database
*
* @param[in] h Clicon handle
* @param[in] db Database name
* @param[in] newdb New Database name; if NULL, then same as old
* @param[in] suffix Suffix to append to new database name
* @retval -1 Error
* @retval 0 OK
* @retval -1 Error
* @note if newdb and suffix are null, OK is returned as it is a no-op
*/
int

View file

@ -87,9 +87,10 @@
#define handle(xh) (assert(text_handle_check(xh)==0),(struct text_handle *)(xh))
/*! Ensure that xt only has a single sub-element and that is "config"
*
* @retval 0 There exists a single "config" sub-element
* @retval -1 Top element not "config" or "config" element not unique or
* other error, check specific clicon_errno, clicon_suberrno
* @retval 0 There exists a single "config" sub-element
*/
static int
singleconfigroot(cxobj *xt,
@ -128,8 +129,9 @@ singleconfigroot(cxobj *xt,
}
/*! Recurse up from x0 up to x0t then create objects from x1t down to new object x1
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 OK
*
* @retval 0 OK
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
*/
static int
xml_copy_bottom_recurse(cxobj *x0t,
@ -206,8 +208,9 @@ xml_copy_bottom_recurse(cxobj *x0t,
}
/*! Copy an XML tree bottom-up
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 OK
*
* @retval 0 OK
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
*/
static int
xml_copy_from_bottom(cxobj *x0t,
@ -248,8 +251,8 @@ xml_copy_from_bottom(cxobj *x0t,
* @param[in] yspec Top-level yang spec
* @param[in] xt XML tree
* @param[out] msdiff Modules-state differences
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 OK
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
*
* The modstate difference contains:
* - if there is a modstate
@ -393,10 +396,11 @@ text_read_modstate(clicon_handle h,
}
/*! Check if nacm only contains default values, if so disable NACM
*
* @param[in] xt Top-level XML
* @param[in] yspec YANG spec
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 OK
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
*/
static int
disable_nacm_on_empty(cxobj *xt,
@ -439,6 +443,7 @@ disable_nacm_on_empty(cxobj *xt,
}
/*! Common read function that reads an XML tree from file
*
* @param[in] th Datastore text handle
* @param[in] db Symbolic database name, eg "candidate", "running"
* @param[in] yb How to bind yang to XML top-level when parsing
@ -447,9 +452,9 @@ disable_nacm_on_empty(cxobj *xt,
* @param[out] de If set, return db-element status (eg empty flag)
* @param[out] msdiff If set, return modules-state differences
* @param[out] xerr XML error if retval is 0
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval 1 OK
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note Use of 1 for OK
* @note retval 0 is NYI because calling functions cannot handle it yet
* XXX if this code pass tests this code can be rewritten, esp the modstate stuff
@ -657,6 +662,7 @@ xmldb_readfile(clicon_handle h,
}
/*! Get content of database using xpath. return a set of matching sub-trees
*
* The function returns a minimal tree that includes all sub-trees that match
* xpath.
* This is a clixon datastore plugin of the the xmldb api
@ -669,9 +675,9 @@ xmldb_readfile(clicon_handle h,
* @param[out] xret Single return XML tree. Free with xml_free()
* @param[out] msdiff If set, return modules-state differences
* @param[out] xerr XML error if retval is 0
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval 1 OK
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note Use of 1 for OK
* @see xmldb_get the generic API function
*/
@ -816,6 +822,7 @@ xmldb_get_nocache(clicon_handle h,
}
/*! Get content of database using xpath. return a set of matching sub-trees
*
* The function returns a minimal tree that includes all sub-trees that match
* xpath.
* This is a clixon datastore plugin of the the xmldb api
@ -828,9 +835,9 @@ xmldb_get_nocache(clicon_handle h,
* @param[out] xtop Single return XML tree. Free with xml_free()
* @param[out] msdiff If set, return modules-state differences
* @param[out] xerr XML error if retval is 0
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval 1 OK
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note Use of 1 for OK
* @see xmldb_get the generic API function
*/
@ -1007,6 +1014,7 @@ xmldb_get_cache(clicon_handle h,
}
/*! Get the raw cache of whole tree
*
* Useful for some higer level usecases for optimized access
* This is a clixon datastore plugin of the the xmldb api
* @param[in] h Clicon handle
@ -1018,9 +1026,9 @@ xmldb_get_cache(clicon_handle h,
* @param[out] xret Single return XML tree. Free with xml_free()
* @param[out] msdiff If set, return modules-state differences
* @param[out] xerr XML error if retval is 0
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval 1 OK
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note Use of 1 for OK
*/
static int
@ -1158,14 +1166,15 @@ xmldb_get_zerocopy(clicon_handle h,
}
/*! Get content of datastore and return a copy of the XML tree
*
* @param[in] h Clicon handle
* @param[in] db Name of database to search in, eg "running"
* @param[in] nsc XML namespace context for XPATH
* @param[in] xpath String with XPATH syntax. or NULL for all
* @param[out] xret Single return XML tree. Free with xml_free()
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval 1 OK
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note Use of 1 for OK
* @code
* if (xmldb_get(xh, "running", NULL, "/interfaces/interface[name="eth"]", &xt) < 0)
@ -1202,9 +1211,9 @@ xmldb_get(clicon_handle h,
* @param[out] xret Single return XML tree. Free with xml_free()
* @param[out] msdiff If set, return modules-state differences (upgrade code)
* @param[out] xerr XML error if retval is 0
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval 1 OK
* @retval 0 Parse OK but yang assigment not made (or only partial) and xerr set
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note Use of 1 for OK
* @code
* cxobj *xt;
@ -1287,8 +1296,8 @@ xmldb_get0(clicon_handle h,
*
* @param[in] h Clicon handle
* @param[in] db Name of datastore
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @retval 0 OK
* @retval 0 OK
* @retval -1 General error, check specific clicon_errno, clicon_suberrno
* @note "Clear" an xml tree means removing default values and resetting all flags.
* @see xmldb_get0
*/
@ -1316,6 +1325,7 @@ xmldb_get0_clear(clicon_handle h,
}
/*! Free xml tree obtained with xmldb_get0
*
* @param[in] h Clixon handle
* @param[in,out] xp Pointer to XML cache.
* @retval 0 Always.

View file

@ -95,9 +95,9 @@
* @param[in] ns (Expected) Namespace of attribute
* @param[out] cbret Error message (if retval=0)
* @param[out] valp Malloced value (if retval=1)
* @retval -1 Error
* @retval 0 Failed (cbret set)
* @retval 1 OK
* @retval 0 Failed (cbret set)
* @retval -1 Error
*/
static int
attr_ns_value(cxobj *x,
@ -153,9 +153,9 @@ attr_ns_value(cxobj *x,
* @param[in] x1bstr Body string of x1
* @param[in] y Yang of x0 (and x1)
* @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0.
* @retval -1 Error
* @retval 0 Failed (cbret set)
* @retval 1 OK
* @retval 0 Failed (cbret set)
* @retval -1 Error
*/
static int
check_body_namespace(cxobj *x0,
@ -273,9 +273,9 @@ check_body_namespace(cxobj *x0,
* @param[in] x1 XML tree which modifies base
* @param[in] y0 Yang spec corresponding to xml-node x0. NULL if x0 is NULL
* @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0.
* @retval -1 Error
* @retval 0 Failed (cbret set)
* @retval 1 OK
* @retval 0 Failed (cbret set)
* @retval -1 Error
* @note There may be some combination cases (x0+x1) that are not covered in this function.
*/
static int
@ -331,8 +331,9 @@ check_when_condition(cxobj *x0p,
}
/*! Check if x0/y0 is part of other choice/case than y1 recursively , if so purge
* @retval 0 No, y0 it is not in other case than y1
*
* @retval 1 yes, y0 is in other case than y1
* @retval 0 No, y0 it is not in other case than y1
*/
static int
choice_is_other(yang_stmt *y0c,
@ -428,6 +429,7 @@ choice_delete_other(cxobj *x0,
}
/*! Modify a base tree x0 with x1 with yang spec y according to operation op
*
* @param[in] h Clicon handle
* @param[in] x0 Base xml tree (can be NULL in add scenarios)
* @param[in] x0p Parent of x0
@ -440,9 +442,9 @@ choice_delete_other(cxobj *x0,
* @param[in] xnacm NACM XML tree (only if !permit)
* @param[in] permit If set, no NACM tests using xnacm required
* @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0.
* @retval -1 Error
* @retval 0 Failed (cbret set)
* @retval 1 OK
* @retval 0 Failed (cbret set)
* @retval -1 Error
* Assume x0 and x1 are same on entry and that y is the spec
* @see text_modify_top
* RFC 7950 Sec 7.7.9(leaf-list), 7.8.6(lists)
@ -1007,6 +1009,7 @@ text_modify(clicon_handle h,
} /* text_modify */
/*! Modify a top-level base tree x0 with modification tree x1
*
* @param[in] h Clicon handle
* @param[in] x0t Base xml tree (can be NULL in add scenarios)
* @param[in] x1t XML tree which modifies base
@ -1016,9 +1019,9 @@ text_modify(clicon_handle h,
* @param[in] xnacm NACM XML tree (only if !permit)
* @param[in] permit If set, no NACM tests using xnacm required
* @param[out] cbret Initialized cligen buffer. Contains return XML if retval is 0.
* @retval -1 Error
* @retval 0 Failed (cbret set)
* @retval 1 OK
* @retval 0 Failed (cbret set)
* @retval -1 Error
* @see text_modify
*/
static int