Support properties of arbitrary type

1 files changed, 36 insertions, 3 deletions

diff --git a/pcilib/unit.h b/pcilib/unit.h
index 3e49174..2351f26 100644
--- a/pcilib/unit.h
+++ b/pcilib/unit.h
@@ -35,14 +35,47 @@ struct pcilib_unit_context_s {
 extern "C" {
 #endif
 
+/**
+ * Use this function to add new unit definitions into the model. It is error to re-register
+ * already registered unit. The function will copy the context of unit description, but name, 
+ * transform, and other strings in the structure are considered to have static duration 
+ * and will not be copied. On error no new units are initalized.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] n - number of units to initialize. It is OK to pass 0 if protocols variable is NULL terminated (last member of protocols array have all members set to 0)
+ * @param[in] desc - unit descriptions
+ * @return - error or 0 on success
+ */
 int pcilib_add_units(pcilib_t *ctx, size_t n, const pcilib_unit_description_t *desc);
-void pcilib_clean_units(pcilib_t *ctx);
+
+/**
+ * Destroys data associated with units. This is an internal function and will
+ * be called during clean-up.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] start - specifies first unit to clean (used to clean only part of the units to keep the defined state if pcilib_add_units has failed)
+ */
+void pcilib_clean_units(pcilib_t *ctx, pcilib_unit_t start);
 
 pcilib_unit_t pcilib_find_unit_by_name(pcilib_t *ctx, const char *unit);
 pcilib_unit_transform_t *pcilib_find_transform_by_unit_names(pcilib_t *ctx, const char *from, const char *to);
 
-    // value is modified
-int pcilib_transform_unit(pcilib_t *ctx, pcilib_unit_transform_t *trans, pcilib_value_t *value);
+/**
+ * Converts value to the requested units. It is error to convert values with unspecified units.
+ * This is internal function, use pcilib_value_convert_value_unit instead.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] trans - the requested unit transform 
+ * @param[in,out] value - the value to be converted (changed on success)
+ * @return - error or 0 on success
+ */
+int pcilib_transform_unit(pcilib_t *ctx, const pcilib_unit_transform_t *trans, pcilib_value_t *value);
+
+/**
+ * Converts value to the requested units. It is error to convert values with unspecified units.
+ * This is internal function, use pcilib_value_convert_value_unit instead.
+ * @param[in,out] ctx - pcilib context
+ * @param[in] name - specifies the requested unit of the value
+ * @param[in,out] value - the value to be converted (changed on success)
+ * @return - error or 0 on success
+ */
 int pcilib_transform_unit_by_name(pcilib_t *ctx, const char *to, pcilib_value_t *value);