[Libvirt-cim] [PATCH] [CU] Commented some structures in the std_association.h file

[Richard Maciel]

# HG changeset patch
# User Richard Maciel <richardm at br.ibm.com>
# Date 1226604430 7200
# Node ID b26dabfc31b3c528fe632c011ce76fd5426e0fd3
# Parent  5fbf96fedcf7df32fccc3f989aa4520af8c9a264
[CU] Commented some structures in the std_association.h file

* Commented the std_assoc and std_assoc_info structures
to make easier for newbies to learn how to create new associations.

Signed-off-by: Richard Maciel <richardm at br.ibm.com>

diff -r 5fbf96fedcf7 -r b26dabfc31b3 std_association.h
--- a/std_association.h	Wed Oct 08 10:32:18 2008 -0700
+++ b/std_association.h	Thu Nov 13 17:27:10 2008 -0200
@@ -31,24 +31,61 @@
                                       struct std_assoc_info *info,
                                       struct inst_list *list);
 
-typedef CMPIInstance *(*make_ref_t)(const CMPIObjectPath *,
-                                    const CMPIInstance *,
+typedef CMPIInstance *(*make_ref_t)(const CMPIObjectPath *ref,
+                                    const CMPIInstance *inst,
                                     struct std_assoc_info *info,
-                                    struct std_assoc *);
+                                    struct std_assoc *assoc);
 
+/*
+ * std_assoc is the definition that the developer puts in their source file. It
+ * defines an association relationship between a set of source and target
+ * classes, through a named (set of) association classes and the function
+ * handler which does the work. 
+ * It must be registered using the macro STDA_AssocMIStub. 
+ */
 struct std_assoc {
         char **source_class;
+        /* Defines the list of possible classes that can be passed to the 
+           association for this case */
+
         char *source_prop;
+        /* Defines the property of the association class that refers 
+           to the input (source class) of this case. This must match
+           that of the schema, and is used for automatic generation of 
+           the reference object in the References() or ReferenceNames()
+           operation */
 
         char **target_class;
+        /* Same as source_class, applied for target */
+
         char *target_prop;
+        /* Same as source_prop, applied for target */
     
         char **assoc_class;
+        /* Defines the list of association classes which implement this
+           association */
 
         assoc_handler_t handler;
+        /* Function handler responsible for doing the association and
+           returning the list of target instances of the association.
+           The handler function receives the reference of the source 
+           class of the association and must map it to a list of 
+           CMPIInstance objects (targets of the association). */
+
         make_ref_t make_ref;
+        /* Function handler responsible for creating an instance of the
+           association class as requested by the References() or
+           ReferenceNames() operation.  
+           The handler function receives the source object path,
+           and the target instance, so it can create the reference which is returned
+           by the function. */
 };
 
+/*
+ * The std_assoc_info is used to keep information related to the query done
+ * All members of this structure are named after the formal CIM association
+ * query components.
+ */
 struct std_assoc_info {
         const char *assoc_class;
         const char *result_class;