glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml

glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml,
glib/tmpl/datalist.sgml, glib/tmpl/date.sgml,
glib/tmpl/datasets.sgml, glib/tmpl/type_conversion.sgml,
glib/tmpl/memory.sgml, glib/tmpl/hash_tables.sgml:
Markup fixes and a few additions.

docs/reference/ChangeLog

@@ -1,3 +1,12 @@
+2001-09-30  Matthias Clasen  <matthiasc@poet.de>
+
+	* glib/tmpl/arrays.sgml,glib/tmpl/arrays_byte.sgml
+	glib/tmpl/arrays_pointer.sgml, glib/tmpl/caches.sgml, 
+	glib/tmpl/datalist.sgml, glib/tmpl/date.sgml, 
+	glib/tmpl/datasets.sgml, glib/tmpl/type_conversion.sgml,
+	glib/tmpl/memory.sgml, glib/tmpl/hash_tables.sgml:
+	Markup fixes and a few additions.
+
 2001-09-27  Matthias Clasen  <matthiasc@poet.de>
 
 	* glib/tmpl/macros.sgml, glib/tmpl/macros_misc.sgml, 

docs/reference/glib/tmpl/arrays.sgml

@@ -69,9 +69,9 @@ added to the #GArray.
 Creates a new #GArray.
 </para>
 
-@zero_terminated: TRUE if the array should have an extra element at the end
+@zero_terminated: %TRUE if the array should have an extra element at the end
-which is set to '0'.
+which is set to 0.
-@clear: TRUE if #GArray elements should be automatically cleared to '0'
+@clear: %TRUE if #GArray elements should be automatically cleared to 0
 when they are allocated.
 @element_size: the size of each element in bytes.
 @Returns: the new #GArray.
@@ -85,11 +85,11 @@ add many elements to the array. Note however that the size of the
 array is still 0.
 </para>
 
-@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared
+@zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared.
-@clear: %TRUE if all bits in the array should be cleared to 0 on allocation
+@clear: %TRUE if all bits in the array should be cleared to 0 on allocation.
-@element_size: size of each element in the array
+@element_size: size of each element in the array.
-@reserved_size: number of elements preallocated
+@reserved_size: number of elements preallocated.
-@Returns: the new #GArray
+@Returns: the new #GArray.
 
 
 <!-- ##### MACRO g_array_append_val ##### -->
@@ -214,13 +214,13 @@ g_array_remove_index().
 
 <!-- ##### FUNCTION g_array_sort ##### -->
 <para>
-Sorts a #GArray using @compare_func which should be a qsort()-style comparison
+Sorts a #GArray using @compare_func which should be a <function>qsort()</function>-style comparison
 function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
 first arg is greater than second arg).
 </para>
 
-@array: a #GArray
+@array: a #GArray.
-@compare_func: comparison function
+@compare_func: comparison function.
 
 
 <!-- ##### FUNCTION g_array_sort_with_data ##### -->
@@ -229,9 +229,9 @@ Like g_array_sort(), but the comparison function receives a user data
 argument.
 </para>
 
-@array: a #GArray
+@array: a #GArray.
-@compare_func: a comparison function
+@compare_func: comparison function.
-@user_data: data to pass to @compare_func
+@user_data: data to pass to @compare_func.
 
 
 <!-- ##### MACRO g_array_index ##### -->
@@ -260,7 +260,7 @@ The return value is cast to the given type.
 <!-- ##### FUNCTION g_array_set_size ##### -->
 <para>
 Sets the size of the array, expanding it if necessary.
-If the array was created with clear set to TRUE, the new elements are set to 0.
+If the array was created with @clear set to %TRUE, the new elements are set to 0.
 </para>
 
 @array: a #GArray.
@@ -271,11 +271,10 @@ If the array was created with clear set to TRUE, the new elements are set to 0.
 <!-- ##### FUNCTION g_array_free ##### -->
 <para>
 Frees the memory allocated for the #GArray.
-If free_segment is TRUE it frees the actual element data as well.
+If @free_segment is %TRUE it frees the actual element data as well.
 </para>
 
 @array: a #GArray.
-@free_segment: if TRUE the actual element data is freed as well.
+@free_segment: if %TRUE the actual element data is freed as well.
-@Returns: 
 
 

docs/reference/glib/tmpl/arrays_byte.sgml

@@ -73,8 +73,8 @@ avoids frequent reallocation, if you are going to add many bytes to
 the array. Note however that the size of the array is still 0.
 </para>
 
-@reserved_size: number of bytes preallocated
+@reserved_size: number of bytes preallocated.
-@Returns: the new #GByteArray
+@Returns: the new #GByteArray.
 
 
 <!-- ##### FUNCTION g_byte_array_append ##### -->
@@ -127,13 +127,13 @@ g_byte_array_remove_index().
 
 <!-- ##### FUNCTION g_byte_array_sort ##### -->
 <para>
-Sorts a byte array, using @compare_func which should be a qsort()-style
+Sorts a byte array, using @compare_func which should be a <function>qsort()</function>-style
 comparison function (returns -1 for first arg is less than second arg, 0 for
 equal, 1 if first arg is greater than second arg).
 </para>
 
-@array: array to sort
+@array: a #GByteArray.
-@compare_func: comparison function
+@compare_func: comparison function.
 
 
 <!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
@@ -141,9 +141,9 @@ equal, 1 if first arg is greater than second arg).
 Like g_byte_array_sort(), but the comparison function takes a user data argument.
 </para>
 
-@array: a #GByteArray
+@array: a #GByteArray.
-@compare_func: comparison function
+@compare_func: comparison function.
-@user_data: data to pass to @compare_func
+@user_data: data to pass to @compare_func.
 
 
 <!-- ##### FUNCTION g_byte_array_set_size ##### -->
@@ -159,11 +159,10 @@ Sets the size of the #GByteArray, expanding it if necessary.
 <!-- ##### FUNCTION g_byte_array_free ##### -->
 <para>
 Frees the memory allocated by the #GByteArray.
-If free_segment is TRUE it frees the actual byte data.
+If free_segment is %TRUE it frees the actual byte data.
 </para>
 
 @array: a #GByteArray.
-@free_segment: if TRUE the actual byte data is freed as well.
+@free_segment: if %TRUE the actual byte data is freed as well.
-@Returns: 
 
 

docs/reference/glib/tmpl/arrays_pointer.sgml

@@ -108,13 +108,13 @@ Removes the first occurrence of the given pointer from the pointer array.
 The following elements are moved down one place.
 </para>
 <para>
-It returns TRUE if the pointer was removed, or FALSE if the pointer
+It returns %TRUE if the pointer was removed, or %FALSE if the pointer
 was not found.
 </para>
 
 @array: a #GPtrArray.
 @data: the pointer to remove.
-@Returns: TRUE if the pointer is removed. FALSE if the pointer is not found
+@Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found
 in the array.
 
 
@@ -137,13 +137,13 @@ does not preserve the order of the array. But it is faster than
 g_ptr_array_remove().
 </para>
 <para>
-It returns TRUE if the pointer was removed, or FALSE if the pointer
+It returns %TRUE if the pointer was removed, or %FALSE if the pointer
 was not found.
 </para>
 
 @array: a #GPtrArray.
 @data: the pointer to remove.
-@Returns: TRUE if the pointer was found in the array.
+@Returns: %TRUE if the pointer was found in the array.
 
 
 <!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
@@ -161,13 +161,13 @@ g_ptr_array_remove_index().
 
 <!-- ##### FUNCTION g_ptr_array_sort ##### -->
 <para>
-Sorts the array, using @compare_func which should be a qsort()-style comparison
+Sorts the array, using @compare_func which should be a <function>qsort()</function>-style comparison
 function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
 first arg is greater than second arg).
 </para>
 
-@array: array to sort
+@array: a #GPtrArray.
-@compare_func: comparison function
+@compare_func: comparison function.
 
 
 <!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
@@ -175,15 +175,15 @@ first arg is greater than second arg).
 Like g_ptr_array_sort(), but the comparison function has a user data argument.
 </para>
 
-@array: array to sort
+@array: a #GPtrArray.
-@compare_func: qsort()-style comparison function
+@compare_func: comparison function.
-@user_data: data to pass to @compare_func
+@user_data: data to pass to @compare_func.
 
 
 <!-- ##### FUNCTION g_ptr_array_set_size ##### -->
 <para>
 Sets the size of the array, expanding it if necessary.
-New elements are set to NULL.
+New elements are set to %NULL.
 </para>
 
 @array: a #GPtrArray.
@@ -206,7 +206,6 @@ Frees all of the memory allocated for the pointer array.
 </para>
 
 @array: a #GPtrArray.
-@free_seg: if TRUE the actual element data is freed as well.
+@free_seg: if %TRUE the actual element data is freed as well.
-@Returns: 
 
 

docs/reference/glib/tmpl/caches.sgml

@@ -2,7 +2,7 @@
 Caches
 
 <!-- ##### SECTION Short_Description ##### -->
-allows sharing of complex data structures to save resources.
+caches allow sharing of complex data structures to save resources.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -35,7 +35,7 @@ a #GCache. It should only be accesssed via the following functions.
 
 <!-- ##### FUNCTION g_cache_new ##### -->
 <para>
-Creates a new GCache.
+Creates a new #GCache.
 </para>
 
 @value_new_func: a function to create a new object given a key.
@@ -45,17 +45,15 @@ does not already exist.
 called by g_cache_remove() when the object is no longer needed (i.e. its
 reference count drops to 0).
 @key_dup_func: a function to copy a key. It is called by
-g_cache_insert() if the key does not already exist in the GCache.
+g_cache_insert() if the key does not already exist in the #GCache.
 @key_destroy_func: a function to destroy a key. It is
 called by g_cache_remove() when the object is no longer needed (i.e. its
 reference count drops to 0).
 @hash_key_func: a function to create a hash value from a key.
 @hash_value_func: a function to create a hash value from a value.
-@key_equal_func: a function to compare two keys. It should return TRUE if
+@key_equal_func: a function to compare two keys. It should return %TRUE if
 the two keys are equivalent.
 @Returns: a new #GCache.
-<!-- # Unused Parameters # -->
-@key_compare_func: 
 
 
 <!-- ##### FUNCTION g_cache_insert ##### -->
@@ -96,7 +94,7 @@ Note that it does not destroy the keys and values which were contained in the
 GCache.
 </para>
 
-@cache: 
+@cache: a #GCache.
 
 
 <!-- ##### FUNCTION g_cache_key_foreach ##### -->
@@ -133,11 +131,11 @@ should free any memory and other resources associated with it.
 <!-- ##### USER_FUNCTION GCacheDupFunc ##### -->
 <para>
 Specifies the type of the @key_dup_func function passed to g_cache_new().
-The function is passed a key (NOT a value as the prototype implies) and
+The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and
 should return a duplicate of the key.
 </para>
 
-@value: the #GCache key to destroy (NOT a #GCache value as it seems).
+@value: the #GCache key to destroy (<emphasis>not</emphasis> a #GCache value as it seems).
 @Returns: a copy of the #GCache key.
 
 

docs/reference/glib/tmpl/datalist.sgml

@@ -10,8 +10,8 @@ Keyed data lists provide lists of arbitrary data elements which can be accessed
 either with a string or with a #GQuark corresponding to the string.
 </para>
 <para>
-The GQuark methods are quicker, since the strings have to be converted to
+The #GQuark methods are quicker, since the strings have to be converted to
-GQuarks anyway.
+#GQuarks anyway.
 </para>
 <para>
 Data lists are used in GTK for associating arbitrary data with
@@ -56,7 +56,7 @@ It should only be accessed via the following functions.
 
 <!-- ##### FUNCTION g_datalist_init ##### -->
 <para>
-Resets the datalist to NULL.
+Resets the datalist to %NULL.
 It does not free any memory or call any destroy functions.
 </para>
 
@@ -98,7 +98,7 @@ Gets a data element.
 
 @datalist: a datalist.
 @key_id: the #GQuark identifying a data element.
-@Returns: the data element, or NULL if it is not found.
+@Returns: the data element, or %NULL if it is not found.
 
 
 <!-- ##### MACRO g_datalist_id_remove_data ##### -->
@@ -117,7 +117,7 @@ Removes an element, without calling its destroy notification function.
 
 @datalist: a datalist.
 @key_id: the #GQuark identifying a data element.
-@Returns: the data previously stored at @key_id, or %NULL if none
+@Returns: the data previously stored at @key_id, or %NULL if none.
 
 
 <!-- ##### MACRO g_datalist_set_data ##### -->
@@ -153,7 +153,7 @@ converted to a #GQuark.
 
 @dl: a datalist.
 @k: the string identifying a data element.
-@Returns: the data element, or NULL if it is not found.
+@Returns: the data element, or %NULL if it is not found.
 
 
 <!-- ##### MACRO g_datalist_remove_data ##### -->

docs/reference/glib/tmpl/datasets.sgml

@@ -94,7 +94,7 @@ Gets the data element corresponding to a #GQuark.
 
 @dataset_location: the location identifying the dataset.
 @key_id: the #GQuark id to identify the data element.
-@Returns: the data element corresponding to the #GQuark, or NULL if it is
+@Returns: the data element corresponding to the #GQuark, or %NULL if it is
 not found.
 
 
@@ -149,7 +149,7 @@ Gets the data element corresponding to a string.
 
 @l: the location identifying the dataset.
 @k: the string identifying the data element.
-@Returns: the data element corresponding to the string, or NULL if it is not
+@Returns: the data element corresponding to the string, or %NULL if it is not
 found.
 
 

docs/reference/glib/tmpl/date.sgml

@@ -52,8 +52,8 @@ representation is valid. Sometimes neither is valid. Use the API.
 </para>
 
 <para>
-glib doesn't contain any time-manipulation functions; however, there
+GLib doesn't contain any time-manipulation functions; however, there
-is a #GTime typedef which is equivalent to time_t, and a #GTimeVal
+is a #GTime typedef which is equivalent to <type>time_t</type>, and a #GTimeVal
 struct which represents a more precise time (with microseconds). You
 can request the current time as a #GTimeVal with g_get_current_time().
 </para>
@@ -78,8 +78,8 @@ Represents a precise time, with seconds and microseconds. Same as the
 <function>gettimeofday()</function> UNIX call.
 </para>
 
-@tv_sec: 
+@tv_sec: seconds.
-@tv_usec: 
+@tv_usec: microseconds.
 
 <!-- ##### FUNCTION g_get_current_time ##### -->
 <para>
@@ -98,7 +98,7 @@ may have limited precision, depending on hardware and operating system; don't
 rely on the exact length of the sleep.
 </para>
 
-@microseconds: number of microseconds to pause
+@microseconds: number of microseconds to pause.
 
 
 <!-- ##### FUNCTION g_time_val_add ##### -->
@@ -132,7 +132,7 @@ month, and year.
 
 <!-- ##### TYPEDEF GTime ##### -->
 <para>
-Simply a replacement for time_t. Unrelated to GTimer.
+Simply a replacement for <type>time_t</type>. Unrelated to #GTimer.
 </para>
 
 
@@ -156,22 +156,22 @@ Integer representing a day of the month; between 1 and
 <!-- ##### ENUM GDateMonth ##### -->
 <para>
 Enumeration representing a month; values are #G_DATE_JANUARY,
-#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value.
+#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
 </para>
 
-@G_DATE_BAD_MONTH: 
+@G_DATE_BAD_MONTH: invalid value.
-@G_DATE_JANUARY: 
+@G_DATE_JANUARY: January.
-@G_DATE_FEBRUARY: 
+@G_DATE_FEBRUARY: February.
-@G_DATE_MARCH: 
+@G_DATE_MARCH: March.
-@G_DATE_APRIL: 
+@G_DATE_APRIL: April.
-@G_DATE_MAY: 
+@G_DATE_MAY: May.
-@G_DATE_JUNE: 
+@G_DATE_JUNE: June.
-@G_DATE_JULY: 
+@G_DATE_JULY: July.
-@G_DATE_AUGUST: 
+@G_DATE_AUGUST: August.
-@G_DATE_SEPTEMBER: 
+@G_DATE_SEPTEMBER: September.
-@G_DATE_OCTOBER: 
+@G_DATE_OCTOBER: October.
-@G_DATE_NOVEMBER: 
+@G_DATE_NOVEMBER: November.
-@G_DATE_DECEMBER: 
+@G_DATE_DECEMBER: December.
 
 <!-- ##### TYPEDEF GDateYear ##### -->
 <para>
@@ -187,14 +187,14 @@ Enumeration representing a day of the week; #G_DATE_MONDAY,
 #G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
 </para>
 
-@G_DATE_BAD_WEEKDAY: 
+@G_DATE_BAD_WEEKDAY: invalid value.
-@G_DATE_MONDAY: 
+@G_DATE_MONDAY: Monday.
-@G_DATE_TUESDAY: 
+@G_DATE_TUESDAY: Tuesday.
-@G_DATE_WEDNESDAY: 
+@G_DATE_WEDNESDAY: Wednesday.
-@G_DATE_THURSDAY: 
+@G_DATE_THURSDAY: Thursday.
-@G_DATE_FRIDAY: 
+@G_DATE_FRIDAY: Friday.
-@G_DATE_SATURDAY: 
+@G_DATE_SATURDAY: Saturday.
-@G_DATE_SUNDAY: 
+@G_DATE_SUNDAY: Sunday.
 
 <!-- ##### MACRO G_DATE_BAD_DAY ##### -->
 <para>
@@ -219,12 +219,12 @@ Represents an invalid year.
 
 <!-- ##### FUNCTION g_date_new ##### -->
 <para>
-Allocate a #GDate and initialize it to a sane state. The new date will
+Allocates a #GDate and initializes it to a sane state. The new date will
 be cleared (as if you'd called g_date_clear()) but invalid (it won't
 represent an existing day). Free the return value with g_date_free().
 </para>
 
-@Returns: The newly-allocated #GDate
+@Returns: a newly-allocated #GDate.
 
 
 <!-- ##### FUNCTION g_date_new_dmy ##### -->
@@ -234,10 +234,10 @@ day/month/year triplet you pass in represents an existing day, the
 returned date will be valid.
 </para>
 
-@day: Day of the month
+@day: day of the month.
-@month: Month of the year
+@month: month of the year.
-@year: Year
+@year: year
-@Returns: Allocated date initialized with @day, @month, and @year
+@Returns: a newly-allocated #GDate initialized with @day, @month, and @year.
 
 
 <!-- ##### FUNCTION g_date_new_julian ##### -->
@@ -247,98 +247,98 @@ Julian day number you pass in is valid (greater than 0, less than an
 unreasonably large number), the returned date will be valid.
 </para>
 
-@julian_day: Days since January 1, Year 1
+@julian_day: days since January 1, Year 1.
-@Returns: Allocated date initialized with @julian_day
+@Returns: a newly-allocated #GDate initialized with @julian_day.
 
 
 <!-- ##### FUNCTION g_date_clear ##### -->
 <para>
-Initialize one or more #GDate structs to a sane but invalid
+Initializes one or more #GDate structs to a sane but invalid
 state. The cleared dates will not represent an existing date, but will
 not contain garbage. Useful to init a date declared on the stack.
 Validity can be tested with g_date_valid().
 </para>
 
-@date: Pointer to one or more dates to clear
+@date: pointer to one or more dates to clear.
-@n_dates: Number of dates to clear
+@n_dates: number of dates to clear.
 
 
 <!-- ##### FUNCTION g_date_free ##### -->
 <para>
-Free a #GDate returned from g_date_new()
+Frees a #GDate returned from g_date_new().
 </para>
 
-@date: Date to free
+@date: a #GDate.
 
 
 <!-- ##### FUNCTION g_date_set_day ##### -->
 <para>
-Set the day of the month for a #GDate. If the resulting day-month-year
+Sets the day of the month for a #GDate. If the resulting day-month-year
 triplet is invalid, the date will be invalid.
 </para>
 
-@date: Date to set the day for
+@date: a #GDate.
-@day: Day to set
+@day: day to set.
 
 
 <!-- ##### FUNCTION g_date_set_month ##### -->
 <para>
-Set the month of the year for a #GDate.  If the resulting
+Sets the month of the year for a #GDate.  If the resulting
- day-month-year triplet is invalid, the date will be invalid.
+day-month-year triplet is invalid, the date will be invalid.
 </para>
 
-@date: Date
+@date: a #GDate.
-@month: Month to set
+@month: month to set.
 
 
 <!-- ##### FUNCTION g_date_set_year ##### -->
 <para>
-Set the year for a #GDate.  If the resulting day-month-year triplet is
+Sets the year for a #GDate. If the resulting day-month-year triplet is
-  invalid, the date will be invalid.
+invalid, the date will be invalid.
 </para>
 
-@date: Date
+@date: a #GDate.
-@year: Year to set
+@year: year to set.
 
 
 <!-- ##### FUNCTION g_date_set_dmy ##### -->
 <para>
-Set the value of a #GDate from a day, month, and year. The DMY triplet
+Sets the value of a #GDate from a day, month, and year. The day-month-year 
-must be valid; if you aren't sure it is, call g_date_valid_dmy() to
+triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to
 check before you set it.
 </para>
 
-@date: Date to set the value of
+@date: a #GDate.
-@day: Day
+@day: day.
-@month: Month
+@month: month.
-@y: Year
+@y: year.
 
 
 <!-- ##### FUNCTION g_date_set_julian ##### -->
 <para>
-Set the value of a #GDate from a Julian day number. 
+Sets the value of a #GDate from a Julian day number.
 </para>
 
-@date: Date to set
+@date: a #GDate.
-@julian_date: Julian day number (days since January 1, Year 1)
+@julian_date: Julian day number (days since January 1, Year 1).
 
 
 <!-- ##### FUNCTION g_date_set_time ##### -->
 <para>
-Set the value of a date from a #GTime (time_t) value. To set the value
+Sets the value of a date from a #GTime (<type>time_t</type>) value. 
-of a date to the current day, you could write:
+To set the value of a date to the current day, you could write:
 <informalexample><programlisting>
-  g_date_set_time(date, time(NULL));
+g_date_set_time(date, time(NULL));
 </programlisting></informalexample>
 </para>
 
-@date: Date to update
+@date: a #GDate.
-@time: #GTime value to set
+@time: #GTime value to set.
 
 
 <!-- ##### FUNCTION g_date_set_parse ##### -->
 <para>
-Parse a user-inputted string @str, and try to figure out what date it
+Parses a user-inputted string @str, and try to figure out what date it
 represents, taking the current locale into account. If the string is
 successfully parsed, the date will be valid after the call. Otherwise,
 it will be invalid. You should check using g_date_valid() to see
@@ -353,86 +353,86 @@ user means by a given string (and it does work pretty well in that
 capacity).
 </para>
 
-@date: Date to fill in
+@date: a #GDate to fill in.
-@str: String to parse
+@str: string to parse.
 
 
 <!-- ##### FUNCTION g_date_add_days ##### -->
 <para>
-Increment a date some number of days. To move forward by weeks, add
+Increments a date some number of days. To move forward by weeks, add
 weeks*7 days. The date must be valid.
 </para>
 
-@date: The date to increment
+@date: a #GDate to increment.
-@n_days: Number of days to move the date forward
+@n_days: number of days to move the date forward.
 
 
 <!-- ##### FUNCTION g_date_subtract_days ##### -->
 <para>
-Move a date some number of days into the past. To move by weeks, just
+Moves a date some number of days into the past. To move by weeks, just
-move by weeks*7 days. Date must be valid.
+move by weeks*7 days. The date must be valid.
 </para>
 
-@date: Date to decrement
+@date: a #GDate to decrement.
-@n_days: Number of days to move
+@n_days: number of days to move.
 
 
 <!-- ##### FUNCTION g_date_add_months ##### -->
 <para>
-Increment a date by some number of months. If the day of the month is
+Increments a date by some number of months. If the day of the month is
 greater than 28, this routine may change the day of the month (because
 the destination month may not have the current day in it). The date
 must be valid.
 </para>
 
-@date: Date to increment
+@date: a #GDate to increment.
-@n_months: Number of months to move forward
+@n_months: number of months to move forward.
 
 
 <!-- ##### FUNCTION g_date_subtract_months ##### -->
 <para>
-Move a date some number of months into the past. If the current day of
+Moves a date some number of months into the past. If the current day of
 the month doesn't exist in the destination month, the day of the month
-may change. Date must be valid.
+may change. The date must be valid.
 </para>
 
-@date: Date to decrement
+@date: a #GDate to decrement.
-@n_months: Number of months to move
+@n_months: number of months to move.
 
 
 <!-- ##### FUNCTION g_date_add_years ##### -->
 <para>
-Increment a date by some number of years. If the date is February 29,
+Increments a date by some number of years. If the date is February 29,
 and the destination year is not a leap year, the date will be changed
 to February 28. The date must be valid.
 </para>
 
-@date: Date to increment
+@date: a #GDate to increment.
-@n_years: Number of years to move forward
+@n_years: number of years to move forward.
 
 
 <!-- ##### FUNCTION g_date_subtract_years ##### -->
 <para>
-Move a date some number of years into the past. If the current day
+Moves a date some number of years into the past. If the current day
 doesn't exist in the destination year (i.e. it's February 29 and you
-move to a non-leap-year) then the day is changed to February 29. Date
+move to a non-leap-year) then the day is changed to February 29. The date
 must be valid.
 </para>
 
-@date: Date to decrement
+@date: a #GDate to decrement.
-@n_years: Number of years to move
+@n_years: number of years to move.
 
 
 <!-- ##### FUNCTION g_date_days_between ##### -->
 <para>
-Compute the number of days between two dates.
+Computes the number of days between two dates.
 If @date2 is prior to @date1, the returned value is negative.
 Both dates must be valid.
 </para>
 
-@date1: The first date
+@date1: the first date.
-@date2: The second date
+@date2: the second date.
-@Returns: The number of days between @date1 and @date2
+@Returns: the number of days between @date1 and @date2.
 
 
 <!-- ##### FUNCTION g_date_compare ##### -->
@@ -441,72 +441,72 @@ Both dates must be valid.
 dates must be valid.
 </para>
 
-@lhs: First date to compare
+@lhs: first date to compare.
-@rhs: Second date to compare
+@rhs: second date to compare.
 @Returns: 0 for equal, less than zero if @lhs is less than @rhs,
-greater than zero if @lhs is greater than @rhs
+greater than zero if @lhs is greater than @rhs.
 
 
 <!-- ##### FUNCTION g_date_clamp ##### -->
 <para>
-If @date is prior to @min_date, set @date equal to @min_date.
+If @date is prior to @min_date, sets @date equal to @min_date.
-If @date falls after @max_date, set @date equal to @max_date.
+If @date falls after @max_date, sets @date equal to @max_date.
 Either @min_date and @max_date may be %NULL.  All non-%NULL dates
 must be valid.
 </para>
 
-@date: Date to clamp
+@date: a #GDate to clamp.
-@min_date: Minimum accepted value for @date
+@min_date: minimum accepted value for @date.
-@max_date: Maximum accepted value for @date
+@max_date: maximum accepted value for @date.
 
 
 <!-- ##### FUNCTION g_date_order ##### -->
 <para>
-Check if @date1 is less than or equal to @date2,
+Checks if @date1 is less than or equal to @date2,
 and swap the values if this is not the case.
 </para>
 
-@date1: The first date
+@date1: the first date.
-@date2: The second date
+@date2: the second date.
 
 
 <!-- ##### FUNCTION g_date_get_day ##### -->
 <para>
-Return the day of the month; the #GDate must be valid.
+Returns the day of the month. The date must be valid.
 </para>
 
-@date: Date to extract the day of the month from
+@date: a #GDate to extract the day of the month from.
-@Returns: Day of the month
+@Returns: day of the month.
 
 
 <!-- ##### FUNCTION g_date_get_month ##### -->
 <para>
-Accessor for the month of the year. Date must be valid.
+Returns the month of the year. The date must be valid.
 </para>
 
-@date: Date to get the month from
+@date: a #GDate to get the month from.
-@Returns: A #GDateMonth
+@Returns: month of the year as a #GDateMonth.
 
 
 <!-- ##### FUNCTION g_date_get_year ##### -->
 <para>
-Accessor; returns the year of a #GDate. The date must be valid.
+Returns the year of a #GDate. The date must be valid.
 </para>
 
-@date: Date
+@date: a #GDate.
-@Returns: Year in which the date falls
+@Returns: year in which the date falls.
 
 
 <!-- ##### FUNCTION g_date_get_julian ##### -->
 <para>
-Accessor, returns the Julian day or "serial number" of the #GDate. The
+Returns the Julian day or "serial number" of the #GDate. The
 Julian day is simply the number of days since January 1, Year 1; i.e.,
 January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
-etc. Date must be valid.
+etc. The date must be valid.
 </para>
 
-@date: Date to extract the Julian day from
+@date: a #GDate to extract the Julian day from.
-@Returns: Julian day
+@Returns: Julian day.
 
 
 <!-- ##### FUNCTION g_date_get_weekday ##### -->
@@ -514,120 +514,121 @@ etc. Date must be valid.
 Returns the day of the week for a #GDate. The date must be valid.
 </para>
 
-@date: Date
+@date: a #GDate.
-@Returns: Day of the week as a #GDateWeekday
+@Returns: day of the week as a #GDateWeekday.
 
 
 <!-- ##### FUNCTION g_date_get_day_of_year ##### -->
 <para>
-Return the day of the year, where Jan 1 is the first day of the
+Returns the day of the year, where Jan 1 is the first day of the
-year. Date must be valid.
+year. The date must be valid.
 </para>
 
-@date: Date to extract day of year from
+@date: a #GDate to extract day of year from.
-@Returns: Day of the year
+@Returns: day of the year.
 
 
 <!-- ##### FUNCTION g_date_get_days_in_month ##### -->
 <para>
-Return the number of days in a month, taking leap years into account.
+Returns the number of days in a month, taking leap years into account.
 </para>
 
-@month: Month
+@month: month.
-@year: Year
+@year: year.
-@Returns: Number of days in @month during the year @year.
+@Returns: number of days in @month during the @year.
 
 
 <!-- ##### FUNCTION g_date_is_first_of_month ##### -->
 <para>
-Returns TRUE if the date is on the first of a month. Date must be valid.
+Returns %TRUE if the date is on the first of a month. The date must be valid.
 </para>
 
-@date: Date to check
+@date: a #GDate to check.
-@Returns: Boolean, if the date is the first of the month
+@Returns: %TRUE if the date is the first of the month.
 
 
 <!-- ##### FUNCTION g_date_is_last_of_month ##### -->
 <para>
-Returns TRUE if the date is the last day of the month. Date must be valid.
+Returns %TRUE if the date is the last day of the month. The date must be valid.
 </para>
 
-@date: Date to check
+@date: a #GDate to check.
-@Returns: Boolean, if the date is the last day of the month
+@Returns: %TRUE if the date is the last day of the month.
+
 
 
 <!-- ##### FUNCTION g_date_is_leap_year ##### -->
 <para>
-Returns TRUE if the year is a leap year
+Returns %TRUE if the year is a leap year.
 </para>
 
-@year: Year to check
+@year: year to check.
-@Returns: Boolean, if the year is a leap year
+@Returns: %TRUE if the year is a leap year.
 
 
 <!-- ##### FUNCTION g_date_get_monday_week_of_year ##### -->
 <para>
-Return the week of the year, where weeks are understood to start on
+Returns the week of the year, where weeks are understood to start on
 Monday. If the date is before the first Monday of the year, return
-0. Date must be valid.
+0. The date must be valid.
 </para>
 
-@date: Date to use
+@date: a #GDate.
-@Returns: Week of the year
+@Returns: week of the year.
 
 
 <!-- ##### FUNCTION g_date_get_monday_weeks_in_year ##### -->
 <para>
-Return the number of weeks in the year, where weeks are taken to start
+Returns the number of weeks in the year, where weeks are taken to start
-on Monday. Will be 52 or 53. Date must be valid. (Years always have 52
+on Monday. Will be 52 or 53. The date must be valid. (Years always have 52
 7-day periods, plus 1 or 2 extra days depending on whether it's a leap
 year. This function is basically telling you how many Mondays are in
 the year, i.e. there are 53 Mondays if one of the extra days happens
 to be a Monday.)
 </para>
 
-@year: Year
+@year: a year.
-@Returns: Number of Mondays in the year
+@Returns: number of Mondays in the year.
 
 
 <!-- ##### FUNCTION g_date_get_sunday_week_of_year ##### -->
 <para>
-Week of the year during which this date falls, if weeks are understood
+Returns the week of the year during which this date falls, if weeks 
-to being on Sunday. Date must be valid. Can return 0 if the day is
+are understood to being on Sunday. The date must be valid. Can return 0 if 
-before the first Sunday of the year.
+the day is before the first Sunday of the year.
 </para>
 
-@date: Date
+@date: a #GDate.
-@Returns: Week number
+@Returns: week number.
 
 
 <!-- ##### FUNCTION g_date_get_sunday_weeks_in_year ##### -->
 <para>
-Return the number of weeks in the year, where weeks are taken to start
+Returns the number of weeks in the year, where weeks are taken to start
-on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52
+on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52
 7-day periods, plus 1 or 2 extra days depending on whether it's a leap
 year. This function is basically telling you how many Sundays are in
 the year, i.e. there are 53 Sundays if one of the extra days happens
 to be a Sunday.)
 </para>
 
-@year: Year to count weeks in
+@year: year to count weeks in.
-@Returns: Number of weeks
+@Returns: number of weeks.
 
 
 <!-- ##### FUNCTION g_date_strftime ##### -->
 <para>
-Generate a printed representation of the date, in a locale-specific
+Generates a printed representation of the date, in a locale-specific
 way. Works just like the standard C <function>strftime()</function>
 function, but only accepts date-related formats; time-related formats
 give undefined results. Date must be valid.
 </para>
 
-@s: Destination buffer
+@s: destination buffer.
-@slen: Max buffer size
+@slen: buffer size.
-@format: Format string
+@format: format string.
-@date: valid #GDate
+@date: valid #GDate.
-@Returns: number of characters written to the buffer, or 0 the buffer was too small
+@Returns: number of characters written to the buffer, or 0 the buffer was too small.
 
 
 <!-- ##### FUNCTION g_date_to_struct_tm ##### -->
@@ -637,81 +638,81 @@ using the @date value. Initializes the non-date parts with something
 sane but meaningless.
 </para>
 
-@date: Date to set the <structname>struct tm</structname> from
+@date: a #GDate to set the <structname>struct tm</structname> from.
-@tm: <structname>struct tm</structname> to fill
+@tm: <structname>struct tm</structname> to fill.
 
 
 <!-- ##### FUNCTION g_date_valid ##### -->
 <para>
-Returns TRUE if the #GDate represents an existing day. #GDate must not
+Returns %TRUE if the #GDate represents an existing day. The date must not
 contain garbage; it should have been initialized with g_date_clear()
 if it wasn't allocated by one of the g_date_new() variants.
 </para>
 
-@date: Date to check
+@date: a #GDate to check.
 @Returns: Whether the date is valid.
 
 
 <!-- ##### FUNCTION g_date_valid_day ##### -->
 <para>
-Returns TRUE if the day of the month is valid (a day is valid if it's
+Returns %TRUE if the day of the month is valid (a day is valid if it's
 between 1 and 31 inclusive).
 </para>
 
-@day: Day to check.
+@day: day to check.
-@Returns: Boolean, whether the day is valid.
+@Returns: %TRUE if the day is valid.
 
 
 <!-- ##### FUNCTION g_date_valid_month ##### -->
 <para>
-Returns TRUE if the month value is valid. The 12 #GDateMonth
+Returns %TRUE if the month value is valid. The 12 #GDateMonth
 enumeration values are the only valid months.
 </para>
 
-@month: Month
+@month: month.
-@Returns: Boolean, whether the month is valid
+@Returns: %TRUE if the month is valid.
 
 
 <!-- ##### FUNCTION g_date_valid_year ##### -->
 <para>
-Returns TRUE if the year is valid. Any year greater than 0 is valid,
+Returns %TRUE if the year is valid. Any year greater than 0 is valid,
-though there is a 16-bit limit to what GDate will understand.
+though there is a 16-bit limit to what #GDate will understand.
 </para>
 
-@year: Year
+@year: year.
-@Returns: Boolean, whether the year is valid.
+@Returns: %TRUE if the year is valid.
 
 
 <!-- ##### FUNCTION g_date_valid_dmy ##### -->
 <para>
-Returns TRUE if the day/month/year triplet forms a valid, existing day
+Returns %TRUE if the day/month/year triplet forms a valid, existing day
-in the range of days GDate understands (Year 1 or later, no more than
+in the range of days #GDate understands (Year 1 or later, no more than
 a few thousand years in the future).
 </para>
 
-@day: Day
+@day: day.
-@month: Month
+@month: month.
-@year: Year
+@year: year.
-@Returns: Boolean, whether the date is a valid one
+@Returns: %TRUE if the date is a valid one.
 
 
 <!-- ##### FUNCTION g_date_valid_julian ##### -->
 <para>
-Returns TRUE if the Julian day is valid. Anything greater than zero is basically a
+Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a
 valid Julian, though there is a 32-bit limit.
 </para>
 
-@julian_date: Julian day to check
+@julian_date: Julian day to check.
-@Returns: Boolean, whether the Julian day is valid.
+@Returns: %TRUE if the Julian day is valid.
 
 
 <!-- ##### FUNCTION g_date_valid_weekday ##### -->
 <para>
-Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
+Returns %TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
 values are the only valid weekdays.
 </para>
 
-@weekday: Weekday
+@weekday: weekday.
-@Returns: Boolean, whether the weekday is valid.
+@Returns: %TRUE if the weekday is valid.
 
 

docs/reference/glib/tmpl/hash_tables.sgml

@@ -87,7 +87,7 @@ Specifies the type of the hash function which is passed to
 g_hash_table_new() when a #GHashTable is created.
 </para>
 <para>
-The function is passed a key and should return a guint hash value.
+The function is passed a key and should return a #guint hash value.
 The functions g_direct_hash(), g_int_hash() and g_str_hash() provide
 hash functions which can be used when the key is a #gpointer, #gint, and 
 #gchar* respectively.
@@ -108,13 +108,13 @@ lookup.
 <!-- ##### USER_FUNCTION GEqualFunc ##### -->
 <para>
 Specifies the type of a function used to test two values for
-equality. The function should return TRUE if both values are equal and
+equality. The function should return %TRUE if both values are equal and
-FALSE otherwise.
+%FALSE otherwise.
 </para>
 
 @a: a value.
 @b: a value to compare with.
-@Returns: TRUE if @a = @b; FALSE otherwise.
+@Returns: %TRUE if @a = @b; %FALSE otherwise.
 
 
 <!-- ##### FUNCTION g_hash_table_insert ##### -->
@@ -237,14 +237,14 @@ which is passed to g_hash_table_foreach().
 Specifies the type of the function passed to g_hash_table_foreach_remove().
 It is called with each key/value pair, together with the @user_data parameter
 passed to g_hash_table_foreach_remove().
-It should return TRUE if the key/value pair should be removed from the
+It should return %TRUE if the key/value pair should be removed from the
 #GHashTable.
 </para>
 
 @key: a key.
 @value: the value associated with the key.
 @user_data: user data passed to g_hash_table_remove().
-@Returns: TRUE if the key/value pair should be removed from the #GHashTable.
+@Returns: %TRUE if the key/value pair should be removed from the #GHashTable.
 
 
 <!-- ##### MACRO g_hash_table_freeze ##### -->
@@ -275,14 +275,14 @@ This function is deprecated and will be removed in the next major
 
 <!-- ##### FUNCTION g_direct_equal ##### -->
 <para>
-Compares two #gpointer arguments and returns TRUE if they are equal.
+Compares two #gpointer arguments and returns %TRUE if they are equal.
 It can be passed to g_hash_table_new() as the @key_equal_func
 parameter, when using pointers as keys in a #GHashTable.
 </para>
 
 @v: a key.
 @v2: a key to compare with @v.
-@Returns: TRUE if the two keys match.
+@Returns: %TRUE if the two keys match.
 
 
 <!-- ##### FUNCTION g_direct_hash ##### -->
@@ -298,7 +298,7 @@ using gpointer values as keys in a #GHashTable.
 
 <!-- ##### FUNCTION g_int_equal ##### -->
 <para>
-Compares the two #gint values being pointed to and returns TRUE if they are
+Compares the two #gint values being pointed to and returns %TRUE if they are
 equal.
 It can be passed to g_hash_table_new() as the @key_equal_func
 parameter, when using pointers to integers as keys in a #GHashTable.
@@ -306,14 +306,14 @@ parameter, when using pointers to integers as keys in a #GHashTable.
 
 @v: a pointer to a #gint key.
 @v2: a pointer to a #gint key to compare with @v.
-@Returns: TRUE if the two keys match.
+@Returns: %TRUE if the two keys match.
 
 
 <!-- ##### FUNCTION g_int_hash ##### -->
 <para>
 Converts a pointer to a #gint to a hash value.
 It can be passed to g_hash_table_new() as the @hash_func parameter, when
-using pointers to gint values as keys in a #GHashTable.
+using pointers to #gint values as keys in a #GHashTable.
 </para>
 
 @v: a pointer to a #gint key.
@@ -322,14 +322,14 @@ using pointers to gint values as keys in a #GHashTable.
 
 <!-- ##### FUNCTION g_str_equal ##### -->
 <para>
-Compares two strings and returns TRUE if they are equal.
+Compares two strings and returns %TRUE if they are equal.
 It can be passed to g_hash_table_new() as the @key_equal_func
 parameter, when using strings as keys in a #GHashTable.
 </para>
 
 @v: a key.
 @v2: a key to compare with @v.
-@Returns: TRUE if the two keys match.
+@Returns: %TRUE if the two keys match.
 
 
 <!-- ##### FUNCTION g_str_hash ##### -->

docs/reference/glib/tmpl/memory.sgml

@@ -22,87 +22,72 @@ This also means that there is no need to check if the call succeeded.
 
 <!-- ##### MACRO g_new ##### -->
 <para>
-Allocates @count elements of type @type.
+Allocates @n_structs elements of type @struct_type.
 The returned pointer is cast to a pointer to the given type.
-If @count is 0 it returns NULL.
+If @count is 0 it returns %NULL.
 </para>
 
-@struct_type: 
+@struct_type: the type of the elements to allocate.
-@n_structs: 
+@n_structs: the number of elements to allocate.
-@Returns: a pointer to the allocated memory, cast to a pointer to @type.
+@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
-<!-- # Unused Parameters # -->
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
 
 
 <!-- ##### MACRO g_new0 ##### -->
 <para>
-Allocates @count elements of type @type, initialized to 0's.
+Allocates @n_structs elements of type @struct_type, initialized to 0's.
 The returned pointer is cast to a pointer to the given type.
-If @count is 0 it returns NULL.
+If @count is 0 it returns %NULL.
 </para>
 
-@struct_type: 
+@struct_type: the type of the elements to allocate.
-@n_structs: 
+@n_structs: the number of elements to allocate.
-@Returns: a pointer to the allocated memory, cast to a pointer to @type.
+@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
-<!-- # Unused Parameters # -->
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
 
 
 <!-- ##### MACRO g_renew ##### -->
 <para>
 Reallocates the memory pointed to by @mem, so that it now has space for
-@count elements of type @type. It returns the new address of the memory,
+@n_struct elements of type @struct_type. It returns the new address of 
-which may have been moved.
+the memory, which may have been moved.
 </para>
 
-@struct_type: 
+@struct_type: the type of the elements to allocate.
 @mem: the currently allocated memory.
-@n_structs: 
+@n_structs: the number of elements to allocate.
-@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
+@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
-<!-- # Unused Parameters # -->
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
 
 
 <!-- ##### FUNCTION g_malloc ##### -->
 <para>
-Allocates @size bytes of memory.
+Allocates @n_bytes bytes of memory.
-If @size is 0 it returns NULL.
+If @n_bytes is 0 it returns %NULL.
 </para>
 
-@n_bytes: 
+@n_bytes: the number of bytes to allocate.
 @Returns: a pointer to the allocated memory.
-<!-- # Unused Parameters # -->
-@size: the number of bytes to allocate.
 
 
 <!-- ##### FUNCTION g_malloc0 ##### -->
 <para>
-Allocates @size bytes of memory, initialized to 0's.
+Allocates @n_bytes bytes of memory, initialized to 0's.
-If @size is 0 it returns NULL.
+If @n_bytes is 0 it returns %NULL.
 </para>
 
-@n_bytes: 
+@n_bytes: the number of bytes to allocate.
 @Returns: a pointer to the allocated memory.
-<!-- # Unused Parameters # -->
-@size: the number of bytes to allocate.
 
 
 <!-- ##### FUNCTION g_realloc ##### -->
 <para>
 Reallocates the memory pointed to by @mem, so that it now has space for
-@size bytes of memory. It returns the new address of the memory, which may
+@n_bytes bytes of memory. It returns the new address of the memory, which may
 have been moved. @mem may be %NULL, in which case it's considered to 
 have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
 </para>
 
 @mem: the memory to reallocate.
-@n_bytes: new size of the memory in bytes
+@n_bytes: new size of the memory in bytes.
 @Returns: the new address of the allocated memory.
-<!-- # Unused Parameters # -->
-@size: the new size of the allocated memory, in bytes.
 
 
 <!-- ##### FUNCTION g_try_malloc ##### -->
@@ -111,8 +96,8 @@ Attempts to allocate @n_bytes, and returns %NULL on failure.
 Contrast with g_malloc(), which aborts the program on failure.
 </para>
 
-@n_bytes: number of bytes to allocate
+@n_bytes: number of bytes to allocate.
-@Returns: the allocated memory, or %NULL
+@Returns: the allocated memory, or %NULL.
 
 
 <!-- ##### FUNCTION g_try_realloc ##### -->
@@ -122,15 +107,15 @@ on failure. Contrast with g_realloc(), which aborts the program
 on failure. If @mem is %NULL, behaves the same as g_try_malloc().
 </para>
 
-@mem: previously-allocated memory, or %NULL
+@mem: previously-allocated memory, or %NULL.
-@n_bytes: number of bytes to allocate
+@n_bytes: number of bytes to allocate.
-@Returns: the allocated memory, or %NULL
+@Returns: the allocated memory, or %NULL.
 
 
 <!-- ##### FUNCTION g_free ##### -->
 <para>
 Frees the memory pointed to by @mem.
-If @mem is NULL it simply returns.
+If @mem is %NULL it simply returns.
 </para>
 
 @mem: the memory to free.
@@ -142,7 +127,7 @@ Allocates @size bytes on the stack; these bytes will be freed when the current
 stack frame is cleaned up.
 </para>
 
-@size: number of bytes to allocate
+@size: number of bytes to allocate.
 
 
 <!-- ##### MACRO g_memmove ##### -->
@@ -151,9 +136,9 @@ Copies a block of memory @n bytes long, from @s to @d.
 The source and destination areas may overlap.
 </para>
 <para>
-In order to use this function, you must include string.h
+In order to use this function, you must include <filename>string.h</filename>
 yourself, because this macro will typically simply resolve
-to memmove() and GLib does not include string.h for you.
+to <function>memmove()</function> and GLib does not include <filename>string.h</filename> for you.
 </para>
 
 @d: the destination address to copy the bytes to.
@@ -164,36 +149,36 @@ to memmove() and GLib does not include string.h for you.
 <!-- ##### FUNCTION g_memdup ##### -->
 <para>
 Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
-from @mem. If @mem is NULL it returns NULL.
+from @mem. If @mem is %NULL it returns %NULL.
 </para>
 
 @mem: the memory to copy.
 @byte_size: the number of bytes to copy.
-@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem
+@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem
-is NULL.
+is %NULL.
 
 
 <!-- ##### STRUCT GMemVTable ##### -->
 <para>
-A set of functions used to perform memory allocation. The same GMemVTable must
+A set of functions used to perform memory allocation. The same #GMemVTable must
 be used for all allocations in the same program; a call to g_mem_set_vtable(),
 if it exists, should be prior to any use of GLib.
 </para>
 
-@malloc: function to use for allocating memory
+@malloc: function to use for allocating memory.
-@realloc: function to use for reallocating memory
+@realloc: function to use for reallocating memory.
-@free: function to use to free memory
+@free: function to use to free memory.
-@calloc: function to use for allocating zero-filled memory
+@calloc: function to use for allocating zero-filled memory.
-@try_malloc: function to use for allocating memory without a default error handler
+@try_malloc: function to use for allocating memory without a default error handler.
-@try_realloc: function to use for reallocating memory without a default error handler
+@try_realloc: function to use for reallocating memory without a default error handler.
 
 <!-- ##### FUNCTION g_mem_set_vtable ##### -->
 <para>
 Sets the #GMemVTable to use for memory allocation. You can use this to provide
 custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
-OTHER GLIB FUNCTIONS. The vtable only needs to provide malloc, realloc, and free
+OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
-functions; GLib can provide default implementations of the others.  The malloc
+functions; GLib can provide default implementations of the others.  The <function>malloc()</function>
-and realloc implementations should return %NULL on failure, GLib will handle
+and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
 error-checking for you. @vtable is copied, so need not persist after this 
 function has been called.
 </para>
@@ -211,15 +196,16 @@ function has been called.
 
 <!-- ##### VARIABLE glib_mem_profiler_table ##### -->
 <para>
-
+A #GMemVTable containing profiling variants of the memory
+allocation functions. Use them together with g_mem_profile()
+in order to get information about the memory allocation pattern
+of your program.
 </para>
 
 
 <!-- ##### FUNCTION g_mem_profile ##### -->
 <para>
 Outputs a summary of memory usage.
-To use this function you must configure glib with the flag
-'--enable-mem-profile=yes' before compiling.
 </para>
 <para>
 It outputs the frequency of allocations of different sizes,
@@ -228,6 +214,9 @@ the total number of bytes which have been freed,
 and the difference between the previous two values, i.e. the number of bytes
 still in use.
 </para>
-
+<para>
+Note that this function will not output anything unless you have
+previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+</para>
 
 

docs/reference/glib/tmpl/type_conversion.sgml

@@ -28,8 +28,8 @@ in a pointer value. Naively, you might try this, but it's incorrect:
  p = (void*) 42;
  i = (int) p;
 </programlisting>
-Again, that example was NOT correct, don't copy it. The problem is
+Again, that example was <emphasis>not</emphasis> correct, don't copy it. 
-that on some systems you need to do this:
+The problem is that on some systems you need to do this:
 <programlisting>
  gpointer p;
  int i;
@@ -66,7 +66,7 @@ storing integers in pointers, and only preserve 32 bits of the
 integer; values outside the range of a 32-bit integer will be mangled.
 </para>
 
-@i: integer to stuff into a pointer
+@i: integer to stuff into a pointer.
 
 
 <!-- ##### MACRO GPOINTER_TO_INT ##### -->
@@ -86,33 +86,35 @@ integer; values outside the range of a 32-bit integer will be mangled.
 
 <!-- ##### MACRO GUINT_TO_POINTER ##### -->
 <para>
-Same as GINT_TO_POINTER(), but for unsigned integers.
+Stuffs an unsigned integer into a pointer type.
 </para>
 
-@u: integer to stuff into the pointer
+@u: unsigned integer to stuff into the pointer.
 
 
 <!-- ##### MACRO GPOINTER_TO_UINT ##### -->
 <para>
-Same as GPOINTER_TO_INT(), but for unsigned integers.
+Extracts an unsigned integer from a pointer. The integer must have
+been stored in the pointer with GUINT_TO_POINTER().
 </para>
 
-@p: pointer to extract an integer from
+@p: pointer to extract an unsigned integer from.
 
 
 <!-- ##### MACRO GSIZE_TO_POINTER ##### -->
 <para>
-
+Stuffs a #gsize into a pointer type.
 </para>
 
-@s: 
+@s: #gsize to stuff into the pointer. 
 
 
 <!-- ##### MACRO GPOINTER_TO_SIZE ##### -->
 <para>
-
+Extracts a #gsize from a pointer. The #gsize must have
+been stored in the pointer with GSIZE_TO_POINTER().
 </para>
 
-@p: 
+@p: pointer to extract a #gsize from.