Rewrite function comments

mysys/array.c

@@ -24,8 +24,23 @@
 #include "m_string.h"
 
 /*
-  Initiate array and alloc space for init_alloc elements. Array is usable
-  even if space allocation failed
+  Initiate dynamic array
+
+  SYNOPSIS
+    init_dynamic_array()
+      array		Pointer to an array
+      element_size	Size of element
+      init_alloc	Number of initial elements
+      alloc_increment	Increment for adding new elements
+
+  DESCRIPTION
+    init_dynamic_array() initiates array and allocate space for 
+    init_alloc eilements. 
+    Array is usable even if space allocation failed.
+
+  RETURN VALUE
+    TRUE	my_malloc_ci() failed
+    FALSE	Ok
 */
 
 my_bool init_dynamic_array(DYNAMIC_ARRAY *array, uint element_size,
@@ -52,8 +67,20 @@ my_bool init_dynamic_array(DYNAMIC_ARRAY *array, uint element_size,
     DBUG_RETURN(TRUE);
   }
   DBUG_RETURN(FALSE);
-}
+} 
 
+/*
+  Insert element at the end of array. Allocate memory if needed.
+
+  SYNOPSIS
+    insert_dynamic()
+      array
+      element
+
+  RETURN VALUE
+    TRUE	Insert failed
+    FALSE	Ok
+*/
 
 my_bool insert_dynamic(DYNAMIC_ARRAY *array, gptr element)
 {
@@ -73,7 +100,22 @@ my_bool insert_dynamic(DYNAMIC_ARRAY *array, gptr element)
 }
 
 
-	/* Alloc room for one element */
+/*
+  Alloc space for next element(s) 
+
+  SYNOPSIS
+    alloc_dynamic()
+      array
+
+  DESCRIPTION
+    alloc_dynamic() checks if there is empty space for at least
+    one element if not tries to allocate space for alloc_increment
+    elements at the end of array.
+
+  RETURN VALUE
+    pointer	Pointer to empty space for element
+    0		Error
+*/
 
 byte *alloc_dynamic(DYNAMIC_ARRAY *array)
 {
@@ -92,7 +134,17 @@ byte *alloc_dynamic(DYNAMIC_ARRAY *array)
 }
 
 
-	/* remove last element from array and return it */
+/*
+  Pop last element from array.
+
+  SYNOPSIS
+    pop_dynamic()
+      array
+  
+  RETURN VALUE    
+    pointer	Ok
+    0		Array is empty
+*/
 
 byte *pop_dynamic(DYNAMIC_ARRAY *array)
 {
@@ -101,6 +153,23 @@ byte *pop_dynamic(DYNAMIC_ARRAY *array)
   return 0;
 }
 
+/*
+  Replace elemnent in array with given element and index
+
+  SYNOPSIS
+    set_dynamic()
+      array
+      element	Element to be inserted
+      idx	Index where element is to be inserted
+
+  DESCRIPTION
+    set_dynamic() replaces element in array. 
+    If idx > max_element insert new element. Allocate memory if needed. 
+ 
+  RETURN VALUE
+    TRUE	Idx was out of range and allocation of new memory failed
+    FALSE	Ok
+*/
 
 my_bool set_dynamic(DYNAMIC_ARRAY *array, gptr element, uint idx)
 {
@@ -128,6 +197,15 @@ my_bool set_dynamic(DYNAMIC_ARRAY *array, gptr element, uint idx)
   return FALSE;
 }
 
+/*
+  Get an element from array by given index
+
+  SYNOPSIS
+    get_dynamic()
+      array	
+      gptr	Element to be returned. If idx > elements contain zeroes.
+      idx	Index of element wanted. 
+*/
 
 void get_dynamic(DYNAMIC_ARRAY *array, gptr element, uint idx)
 {
@@ -143,6 +221,14 @@ void get_dynamic(DYNAMIC_ARRAY *array, gptr element, uint idx)
 }
 
 
+/*
+  Empty array by freeing all memory
+
+  SYNOPSIS
+    delete_dynamic()
+      array	Array to be deleted
+*/
+
 void delete_dynamic(DYNAMIC_ARRAY *array)
 {
   if (array->buffer)
@@ -153,6 +239,14 @@ void delete_dynamic(DYNAMIC_ARRAY *array)
   }
 }
 
+/*
+  Delete element by given index
+
+  SYNOPSIS
+    delete_dynamic_element()
+      array
+      idx	Index of element to be deleted
+*/
 
 void delete_dynamic_element(DYNAMIC_ARRAY *array, uint idx)
 {
@@ -163,6 +257,15 @@ void delete_dynamic_element(DYNAMIC_ARRAY *array, uint idx)
 }
 
 
+/*
+  Free unused memory
+
+  SYNOPSIS
+    freeze_size()
+      array	Array to be freed
+
+*/
+
 void freeze_size(DYNAMIC_ARRAY *array)
 {
   uint elements=max(array->elements,1);

mysys/checksum.c

@@ -14,16 +14,24 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/* Calculate a long checksum for a memoryblock. Used to verify pack_isam */
 
 #include <my_global.h>
 #include "my_sys.h"
 
+/*
+  Calculate a long checksum for a memoryblock. Used to verify pack_isam 
+   
+  SYNOPSIS
+    checksum()
+      mem	Pointer to memory block
+      count	Count of bytes 
+*/
+
 ulong checksum(const byte *mem, uint count)
 {
   ulong crc;
-  for (crc=0; count-- ; mem++)
-    crc=((crc << 1) + *((uchar*) mem)) +
+  for (crc= 0; count-- ; mem++)
+    crc= ((crc << 1) + *((uchar*) mem)) +
       test(crc & ((ulong) 1L << (8*sizeof(ulong)-1)));
   return crc;
 }

mysys/mulalloc.c

@@ -14,12 +14,22 @@
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-	/* Malloc many pointers at the same time */
-	/* format myFlags,ptr,length,ptr,length ... until null ptr */
-
 #include "mysys_priv.h"
 #include <stdarg.h>
 
+/*
+  Malloc many pointers at the same time
+
+  SYNOPSIS
+    my_multi_malloc()
+      myFlags	Flags
+      ... 	Multiple arguments terminated by null ptr
+
+	ptr, length
+	ptr, length
+	NULL
+*/ 
+
 gptr my_multi_malloc(myf myFlags, ...)
 {
   va_list args;

mysys/my_chsize.c

@@ -18,8 +18,22 @@
 #include "mysys_err.h"
 #include "m_string.h"
 
-	/* Change size of file.  Truncate file if shorter,	*/
-	/* else expand with zero.				*/
+/*
+  Change size of file.
+
+  SYNOPSIS
+    my_chsize()
+      fd		File descriptor
+      new_length	New file size
+      MyFlags		Flags
+
+  DESCRIPTION
+    my_chsize() truncates file if shorter, else expand with zero.	
+
+  RETURN VALUE
+    0	Ok
+    1	Error 
+*/
 
 int my_chsize(File fd, my_off_t newlength, myf MyFlags)
 {

mysys/my_div.c

@@ -16,6 +16,14 @@
 
 #include "mysys_priv.h"
 
+/*
+  Get filename of file
+
+  SYNOPSIS
+    my_filename()
+      fd	File descriptor
+*/
+
 my_string my_filename(File fd)
 {
   DBUG_ENTER("my_filename");

mysys/my_error.c

@@ -25,8 +25,15 @@
 const char ** NEAR my_errmsg[MAXMAPS]={0,0,0,0};
 char NEAR errbuff[NRERRBUFFS][ERRMSGSIZE];
 
-/* Error message to user */
-/*VARARGS2*/
+/*
+   Error message to user
+
+   SYNOPSIS
+     my_error()
+       nr	Errno
+       MyFlags	Flags
+       ...	variable list
+*/
 
 int my_error(int nr,myf MyFlags, ...)
 {
@@ -102,7 +109,16 @@ int my_error(int nr,myf MyFlags, ...)
   DBUG_RETURN((*error_handler_hook)(nr, ebuff, MyFlags));
 }
 
-	/* Error as printf */
+/*
+  Error as printf
+
+  SYNOPSIS
+    my_printf_error()
+      error	Errno
+      format	Format string
+      MyFlags	Flags
+      ...	variable list
+*/
 
 int my_printf_error (uint error, const char *format, myf MyFlags, ...)
 {
@@ -115,7 +131,15 @@ int my_printf_error (uint error, const char *format, myf MyFlags, ...)
   return (*error_handler_hook)(error, ebuff, MyFlags);
 }
 
-	/* Give message using error_handler_hook */
+/*
+  Give message using error_handler_hook
+
+  SYNOPSIS
+    my_message()
+      error	Errno
+      str	Error message
+      MyFlags	Flags
+*/
 
 int my_message(uint error, const char *str, register myf MyFlags)
 {

mysys/my_once.c

@@ -24,8 +24,17 @@
 #include "my_static.h"
 #include "mysys_err.h"
 
-	/* alloc for things we don't nead to free */
-	/* No DBUG_ENTER... here to get smaller dbug-startup */
+/*
+  Alloc for things we don't nead to free
+
+  SYNOPSIS
+    my_once_alloc()
+      Size
+      MyFlags
+
+  NOTES
+    No DBUG_ENTER... here to get smaller dbug-startup 
+*/
 
 gptr my_once_alloc(unsigned int Size, myf MyFlags)
 {
@@ -69,7 +78,12 @@ gptr my_once_alloc(unsigned int Size, myf MyFlags)
 } /* my_once_alloc */
 
 
-	/* deallocate everything used by my_once_alloc */
+/*
+  Deallocate everything used by my_once_alloc
+
+  SYNOPSIS
+    my_once_free()
+*/
 
 void my_once_free(void)
 {

mysys/my_open.c

@@ -23,7 +23,18 @@
 #include <share.h>
 #endif
 
-	/* Open a file */
+/*
+  Open a file
+
+  SYNOPSIS
+    my_open()
+      FileName	Fully qualified file name
+      Flags	Read | write 
+      MyFlags	Special flags
+
+  RETURN VALUE
+    File descriptor
+*/
 
 File my_open(const char *FileName, int Flags, myf MyFlags)
 				/* Path-name of file */
@@ -51,7 +62,15 @@ File my_open(const char *FileName, int Flags, myf MyFlags)
 } /* my_open */
 
 
-	/* Close a file */
+/*
+  Close a file
+
+  SYNOPSIS
+    my_close()
+      fd	File sescriptor
+      myf	Special Flags
+      
+*/
 
 int my_close(File fd, myf MyFlags)
 {
@@ -81,6 +100,16 @@ int my_close(File fd, myf MyFlags)
 } /* my_close */
 
 
+/*
+  Register file in my_file_info[]
+   
+  SYNOPSIS
+    my_register_filename()
+      fd
+      FileName
+      type_file_type
+*/
+
 File my_register_filename(File fd, const char *FileName, enum file_type
 			  type_of_file, uint error_message_number, myf MyFlags)
 {