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

[Richard Maciel]

# HG changeset patch
# User Richard Maciel <richardm at br.ibm.com>
# Date 1227019634 7200
# Node ID 80174662fa42b0752b7a1b5b73618c53b66b312a
# Parent  5fbf96fedcf7df32fccc3f989aa4520af8c9a264
[CU](#2) 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.

* Rev 1: Fixed conceptual errors on comments
* Rev 2: changed structures' comment style and changed comments
based on feedback from Kaitlin and Dan

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

diff -r 5fbf96fedcf7 -r 80174662fa42 std_association.h
--- a/std_association.h	Wed Oct 08 10:32:18 2008 -0700
+++ b/std_association.h	Tue Nov 18 12:47:14 2008 -0200
@@ -31,24 +31,62 @@
                                       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 {
+        /* Defines the list of possible classes that can be passed to the 
+           association for this case */
         char **source_class;
+
+        
+        /* 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 *source_prop;
 
+        /* Defines a list of possible classes that can be returned by the
+           association for a given source_class list */
         char **target_class;
+
+        /* Same as source_prop, applied for target */
         char *target_prop;
     
+        /* Defines the list of association classes which are implemented by
+           this handler */
         char **assoc_class;
 
+        /* 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). */
         assoc_handler_t handler;
+
+        /* Function handler responsible for creating an instance of the
+           association class.  
+           The handler function receives the source object path,
+           and the target instance, so it can create the reference which is
+           returned by the function. */
         make_ref_t make_ref;
 };
 
+/*
+ * The std_assoc_info is used to hold the query components of the query done
+ * All members of this structure contain the corresonding formal CIM association
+ * query components.
+ */
 struct std_assoc_info {
         const char *assoc_class;
         const char *result_class;