Better document minimum value of size argument for typed allocations

* include/gc_typed.h (GC_make_descriptor): Provide a better argument
name (in comment).
* include/gc_typed.h (GC_malloc_explicitly_typed,
GC_calloc_explicitly_typed): Explicitly state in comment that the
size of the object in words should not be less than the number of
significant bits in the specified descriptor.

diff --git a/include/gc_typed.h b/include/gc_typed.h
index 8261cd7..06e8261 100644 (file)
--- a/include/gc_typed.h
+++ b/include/gc_typed.h
@@ -50,7 +50,7 @@ typedef GC_word * GC_bitmap;
 typedef GC_word GC_descr;
 
 GC_API GC_descr GC_CALL GC_make_descriptor(const GC_word * /* GC_bitmap bm */,
-                                           size_t /* len */);
+                                size_t /* len (number_of_bits_in_bitmap) */);
                 /* Return a type descriptor for the object whose layout */
                 /* is described by the argument.                        */
                 /* The least significant bit of the first word is one   */
@@ -81,8 +81,10 @@ GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL
         GC_malloc_explicitly_typed(size_t /* size_in_bytes */,
                                    GC_descr /* d */);
                 /* Allocate an object whose layout is described by d.   */
-                /* The resulting object MAY NOT BE PASSED TO REALLOC.   */
-                /* The returned object is cleared.                      */
+                /* The size may NOT be less than the number of          */
+                /* meaningful bits in the bitmap of d multiplied by     */
+                /* sizeof GC_word.  The returned object is cleared.     */
+                /* The returned object may NOT be passed to GC_realloc. */
 
 GC_API GC_ATTR_MALLOC GC_ATTR_ALLOC_SIZE(1) void * GC_CALL
         GC_malloc_explicitly_typed_ignore_off_page(size_t /* size_in_bytes */,
@@ -97,7 +99,9 @@ GC_API GC_ATTR_MALLOC void * GC_CALL
         /* The element size must be a multiple of the byte      */
         /* alignment required for pointers.  E.g. on a 32-bit   */
         /* machine with 16-bit aligned pointers, size_in_bytes  */
-        /* must be a multiple of 2.                             */
+        /* must be a multiple of 2.  The element size may NOT   */
+        /* be less than the number of meaningful bits in the    */
+        /* bitmap of d multiplied by sizeof GC_word.            */
         /* Returned object is cleared.                          */
 
 #ifdef GC_DEBUG