improve documentation of data source

include/ua_types.h

@@ -211,6 +211,8 @@ typedef struct UA_VTable_Entry UA_VTable_Entry;
  * as possible encoding by pointing an entry in the vtable of types. References
  * may either contain a structure with the variants data, or a datasource where
  * this structure may be obtained (using reference counting for async access).
+ *
+ * @{
  */
 
 typedef struct UA_VariantData {
@@ -220,12 +222,17 @@ typedef struct UA_VariantData {
     UA_Int32 *arrayDimensions;
 } UA_VariantData;
 
+/** @brief A datasource is the interface to interact with a local data provider.
+ *
+ *  Implementors of datasources need to provide functions for the callbacks in
+ *  this structure. As a rule, datasources are never copied, but only their
+ *  content. The only way to write into a datasource is via the write-service. */
 typedef struct UA_VariantDataSource {
-    const void *identifier; // whatever id the datasource uses internally. Some provide custom get/write/release functions and don't use this.
-    UA_Int32 (*get)(const void *identifier, const UA_VariantData **); // get the variantdata provided by the datasource. when it is no longer used, it has to be relased.
-    UA_Int32 (*set)(const void **identifier, const UA_VariantData *); // replace the variant data in the datasource. and replace the identifier in the variant for lookups. The VariantData pointer shall no longer be used afterwards
-    void (*release)(const void *identifier, const UA_VariantData *); // release data after every get when the request is finished. so we can have async access to data and free it when the reference count drops to zero
-    void (*delete)(const void *identifier);
+    const void *identifier; /**< whatever id the datasource uses internally. Can be ignored if the datasource functions do not use it. */
+    UA_Int32 (*read)(const void *identifier, const UA_VariantData **); /**< Get the current data from the datasource. When it is no longer used, the data has to be relased. */
+    void (*release)(const void *identifier, const UA_VariantData *); /**< For concurrent access, the datasource needs to know when the last reader releases replaced/deleted data. Release decreases the reference count. */
+    UA_Int32 (*write)(const void **identifier, const UA_VariantData *); /**< Replace the data in the datasource. Also used to replace the identifier pointer for lookups. Do not free the variantdata afterwards! */
+    void (*delete)(const void *identifier); /**< Indicates that the node with the datasource was removed from the namespace. */
 } UA_VariantDataSource;
 
 /** @brief A union of all of the types specified above.
@@ -245,7 +252,7 @@ typedef struct UA_Variant {
     } storage;
 } UA_Variant;
 
-/** @endgroup */
+/** @} */
 
 /** @brief A data value with an associated status code and timestamps. */
 typedef struct UA_DataValue {

src/ua_types.c

@@ -842,7 +842,7 @@ UA_Int32 UA_Variant_copy(UA_Variant const *src, UA_Variant *dst) {
     if(src->storageType == UA_VARIANT_DATA || src->storageType == UA_VARIANT_DATA_NODELETE)
         srcdata = &src->storage.data;
     else {
-        retval |= src->storage.datasource.get(src->storage.datasource.identifier, &srcdata);
+        retval |= src->storage.datasource.read(src->storage.datasource.identifier, &srcdata);
         if(retval != UA_SUCCESS)
             return retval;
     }

src/ua_types_encoding_binary.c

@@ -832,7 +832,7 @@ UA_Int32 UA_Variant_calcSizeBinary(UA_Variant const *p) {
     if(p->storageType == UA_VARIANT_DATA)
         data = &p->storage.data;
     else {
-        if(p->storage.datasource.get(p->storage.datasource.identifier, &data) != UA_SUCCESS)
+        if(p->storage.datasource.read(p->storage.datasource.identifier, &data) != UA_SUCCESS)
             return 0;
     }
         
@@ -876,7 +876,7 @@ UA_TYPE_ENCODEBINARY(UA_Variant,
                      if(src->storageType == UA_VARIANT_DATA)
                          data = &src->storage.data;
                      else {
-                         if(src->storage.datasource.get(src->storage.datasource.identifier, &data) != UA_SUCCESS)
+                         if(src->storage.datasource.read(src->storage.datasource.identifier, &data) != UA_SUCCESS)
                              return UA_ERROR;
                      }
 

tools/generate_builtin.py

@@ -278,8 +278,10 @@ UA_TYPE_METHOD_DECODEXML_NOTIMPL(%(name)s)''')
     printc('''\n''')
     
 	
+shortname = args.outfile.split("/")[-1] 
+print(shortname)
 printh('''/**
- * @file '''+sys.argv[2]+'''.h
+ * @file %(shortname)s.h
  *
  * @brief Autogenerated data types defined in the UA standard
  *
@@ -287,11 +289,19 @@ printh('''/**
  * on host '''+platform.uname()[1]+''' by user '''+getpass.getuser()+''' at '''+ time.strftime("%Y-%m-%d %I:%M:%S")+'''
  */
 
-#ifndef ''' + args.outfile.upper().split("/")[-1] + '''_H_
-#define ''' + args.outfile.upper().split("/")[-1] + '''_H_
+#ifndef ''' + shortname.upper() + '''_H_
+#define ''' + shortname.upper() + '''_H_
 
 #include "ua_types.h"
-#include "ua_types_encoding_binary.h"''')
+#include "ua_types_encoding_binary.h"
+
+/** @ingroup ''' + shortname.split("_")[1] + '''
+ *
+ * @defgroup ''' + shortname + ''' Generated Types
+ *
+ * @brief Data structures that are autogenerated from an XML-Schema.
+ * @{
+ */''')
 if args.with_xml:
 	printh('#include "ua_types_encoding_xml.h"')
 if args.additional_includes:
@@ -365,7 +375,7 @@ for name, element in deferred_types.iteritems():
     else:
 	createStructured(element)
         existing_types.add(name)
-
+printh('/// @} /* end of group */')
 printh('#endif')
 
 fh.close()