Clarify some of the comments.

opal/datatype/opal_datatype_add.c

@@ -109,16 +109,15 @@ int32_t opal_datatype_add( opal_datatype_t* pdtBase, const opal_datatype_t* pdtA
     OPAL_PTRDIFF_TYPE lb, ub, true_lb, true_ub, epsilon, old_true_ub;
 
     /**
-     *from MPI-3, page 84, lines 18-20: Most datatype constructors have
+     * From MPI-3, page 84, lines 18-20: Most datatype constructors have
      * replication count or block length arguments. Allowed values are
      * non-negative integers. If the value is zero, no elements are generated in
      * the type map and there is no effect on datatype bounds or extent.
      */
     if( 0 == count ) return OPAL_SUCCESS;
 
-    /* the extent should always be positive. So a negative
-     * value here have a special meaning ie. default extent as
-     * computed by ub - lb
+    /* the extent should always be positive. So a negative value here have a
+     * special meaning ie. default extent as computed by ub - lb
      */
     if( extent == -1 ) extent = (pdtAdd->ub - pdtAdd->lb);
 

opal/datatype/opal_datatype_internal.h

@@ -150,8 +150,10 @@ struct ddt_elem_id_description {
 };
 typedef struct ddt_elem_id_description ddt_elem_id_description;
 
-/* the basic element. A data description is composed
- * by a set of basic elements.
+/**
+ * The data element description. It is similar to a vector type, a contiguous
+ * blocklen number of basic elements, with a displacement for the first element
+ * and then an extent for all the extra count.
  */
 struct ddt_elem_desc {
     ddt_elem_id_description common;           /**< basic data description and flags */
@@ -162,6 +164,14 @@ struct ddt_elem_desc {
 };
 typedef struct ddt_elem_desc ddt_elem_desc_t;
 
+/**
+ * The loop description, with it's two markers: one for the begining and one for
+ * the end. The initial marker contains the number of repetitions, the number of
+ * elements in the loop, and the extent of each loop. The end marker contains in
+ * addition to the number of elements (so that we can easily pair together the
+ * two markers), the size of the data contained inside and the displacement of
+ * the first element.
+ */
 struct ddt_loop_desc {
     ddt_elem_id_description common;           /**< basic data description and flags */
     uint32_t                loops;            /**< number of elements */