Documentation cleanups

svn path=/trunk/; revision=5652

ChangeLog

@@ -1,3 +1,9 @@
+2007-07-21  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/gunidecomp.c:
+	* glib/gregex.c:
+	* glib/gstring.c: Various doc cleanups.
+
 2007-07-20  Alexander Larsson  <alexl@redhat.com>
 
         * configure.in:

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2007-07-21  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/glib-sections.txt: Additions
+
 2007-07-21  Matthias Clasen  <mclasen@redhat.com>
 	
 	* glib/tmpl/fileutils.sgml: Fix an inaccuracy in the

docs/reference/glib/glib-sections.txt

@@ -39,6 +39,7 @@ gdouble
 <SUBSECTION>
 gsize
 gssize
+goffset
 
 <SUBSECTION Private>
 GLIB_SIZEOF_VOID_P
@@ -85,6 +86,12 @@ G_MAXUINT64
 
 <SUBSECTION>
 G_MAXSIZE
+G_MINSSIZE
+G_MAXSSIZE
+
+<SUBSECTION>
+G_MINOFFSET
+G_MAXOFFSET
 
 <SUBSECTION>
 G_MINFLOAT
@@ -630,6 +637,7 @@ g_thread_functions_for_glib_use
 g_thread_init_glib
 g_thread_error_quark
 g_once_impl
+g_once_init_enter_impl
 atexit
 g_system_thread_assign
 g_system_thread_equal
@@ -1520,6 +1528,7 @@ g_key_file_set_list_separator
 g_key_file_load_from_file
 g_key_file_load_from_data
 g_key_file_load_from_data_dirs
+g_key_file_load_from_dirs
 g_key_file_to_data
 g_key_file_get_start_group
 g_key_file_get_groups
@@ -1683,7 +1692,6 @@ g_completion_free
 <TITLE>Windows Compatibility Functions</TITLE>
 <FILE>windows</FILE>
 MAXPATHLEN
-pipe
 
 g_win32_error_message
 g_win32_getlocale
@@ -2037,6 +2045,8 @@ g_string_insert
 g_string_insert_c
 g_string_insert_unichar
 g_string_insert_len
+g_string_overwrite
+g_string_overwrite_len
 g_string_erase
 g_string_truncate
 g_string_set_size

docs/reference/glib/tmpl/allocators.sgml

@@ -2,7 +2,7 @@
 Memory Allocators
 
 <!-- ##### SECTION Short_Description ##### -->
-deprecated way to allocate chunks of memory for #GList, #GSList and #GNode.
+deprecated way to allocate chunks of memory for GList, GSList and GNode
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/arrays.sgml

@@ -2,7 +2,7 @@
 Arrays
 
 <!-- ##### SECTION Short_Description ##### -->
-arrays of arbitrary elements which grow automatically as elements are added.
+arrays of arbitrary elements which grow automatically as elements are added
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/arrays_byte.sgml

@@ -2,7 +2,7 @@
 Byte Arrays
 
 <!-- ##### SECTION Short_Description ##### -->
-arrays of bytes, which grow automatically as elements are added.
+arrays of bytes, which grow automatically as elements are added
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/arrays_pointer.sgml

@@ -3,7 +3,7 @@ Pointer Arrays
 
 <!-- ##### SECTION Short_Description ##### -->
 arrays of pointers to any type of data, which grow automatically as new
-elements are added.
+elements are added
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/async_queues.sgml

@@ -2,7 +2,7 @@
 Asynchronous Queues
 
 <!-- ##### SECTION Short_Description ##### -->
-asynchronous communication between threads.
+asynchronous communication between threads
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/byte_order.sgml

@@ -2,7 +2,7 @@
 Byte Order Macros
 
 <!-- ##### SECTION Short_Description ##### -->
-a portable way to convert between different byte orders.
+a portable way to convert between different byte orders
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/caches.sgml

@@ -2,7 +2,7 @@
 Caches
 
 <!-- ##### SECTION Short_Description ##### -->
-caches allow sharing of complex data structures to save resources.
+caches allow sharing of complex data structures to save resources
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/completion.sgml

@@ -2,7 +2,7 @@
 Automatic String Completion
 
 <!-- ##### SECTION Short_Description ##### -->
-support for automatic completion using a group of target strings.
+support for automatic completion using a group of target strings
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/conversions.sgml

@@ -2,7 +2,7 @@
 Character Set Conversion
 
 <!-- ##### SECTION Short_Description ##### -->
-convert strings between different character sets using <function>iconv()</function>.
+convert strings between different character sets using iconv()
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/datalist.sgml

@@ -2,7 +2,7 @@
 Keyed Data Lists
 
 <!-- ##### SECTION Short_Description ##### -->
-lists of data elements which are accessible by a string or #GQuark identifier.
+lists of data elements which are accessible by a string or GQuark identifier
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/datasets.sgml

@@ -2,7 +2,7 @@
 Datasets
 
 <!-- ##### SECTION Short_Description ##### -->
-associate groups of data elements with particular memory locations.
+associate groups of data elements with particular memory locations
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/date.sgml

@@ -2,7 +2,7 @@
 Date and Time Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-calendrical calculations and miscellaneous time stuff.
+calendrical calculations and miscellaneous time stuff
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/error_reporting.sgml

@@ -2,7 +2,7 @@
 Error Reporting
 
 <!-- ##### SECTION Short_Description ##### -->
-a system for reporting errors.
+a system for reporting errors
 
 <!-- ##### SECTION Long_Description ##### -->
 

docs/reference/glib/tmpl/fileutils.sgml

@@ -2,7 +2,7 @@
 File Utilities
 
 <!-- ##### SECTION Short_Description ##### -->
-various file-related functions.
+various file-related functions
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -143,7 +143,7 @@ A test to perform on a file using g_file_test().
 
 @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a directory).
     Note that this test will also return %TRUE if the tested file is a symlink
-    to a regular file. 
+    to a regular file.
 @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink.
 @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory.
 @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable.

docs/reference/glib/tmpl/gregex.sgml

@@ -2,7 +2,7 @@
 Perl-compatible regular expressions
 
 <!-- ##### SECTION Short_Description ##### -->
-matches strings against regular expressions.
+matches strings against regular expressions
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/hash_tables.sgml

@@ -3,7 +3,7 @@ Hash Tables
 
 <!-- ##### SECTION Short_Description ##### -->
 associations between keys and values so that given a key the value
-can be found quickly.
+can be found quickly
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/hooks.sgml

@@ -2,7 +2,7 @@
 Hook Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-support for manipulating lists of hook functions.
+support for manipulating lists of hook functions
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/i18n.sgml

@@ -2,7 +2,7 @@
 Internationalization
 
 <!-- ##### SECTION Short_Description ##### -->
-gettext support macros.
+gettext support macros
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/iochannels.sgml

@@ -2,7 +2,7 @@
 IO Channels
 
 <!-- ##### SECTION Short_Description ##### -->
-portable support for using files, pipes and sockets.
+portable support for using files, pipes and sockets
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -120,8 +120,8 @@ On Windows this function returns the file descriptor or socket of the #GIOChanne
 
 <!-- ##### FUNCTION g_io_channel_win32_new_fd ##### -->
 <para>
-Creates a new #GIOChannel given a file descriptor on Windows. This works for
+Creates a new #GIOChannel given a file descriptor on Windows. 
-file descriptors from the C runtime.
+This works for file descriptors from the C runtime.
 </para>
 <para>
 This function works for file descriptors as returned by the open(),
@@ -156,19 +156,17 @@ This function is available only in GLib on Windows.
 Creates a new #GIOChannel given a socket on Windows.
 </para>
 <para>
-This function works for sockets created by Winsock. It's available
+This function works for sockets created by Winsock. 
-only in GLib on Windows.
+It's available only in GLib on Windows.
 </para>
 <para>
-Polling a #GSource created to watch a channel for a socket puts the
+Polling a #GSource created to watch a channel for a socket 
-socket in non-blocking mode. This is a side-effect of the
+puts the socket in non-blocking mode. This is a side-effect 
-implementation and unavoidable.
+of the implementation and unavoidable.
 </para>
 
-@socket: 
+@socket: a Winsock socket
-@Returns: a new #GIOChannel.
+@Returns: a new #GIOChannel
-<!-- # Unused Parameters # -->
-@fd: a Winsock socket.
 
 
 <!-- ##### FUNCTION g_io_channel_win32_new_messages ##### -->
@@ -186,12 +184,13 @@ Windows messages for the window in question.
 
 <!-- ##### FUNCTION g_io_channel_init ##### -->
 <para>
-Initializes a #GIOChannel struct. This is called by each of the above functions
+Initializes a #GIOChannel struct. This is called by each of the 
-when creating a #GIOChannel, and so is not often needed by the application
+above functions when creating a #GIOChannel, and so is not often 
-programmer (unless you are creating a new type of #GIOChannel).
+needed by the application programmer (unless you are creating a 
+new type of #GIOChannel).
 </para>
 
-@channel: a #GIOChannel.
+@channel: a #GIOChannel
 
 
 <!-- ##### FUNCTION g_io_channel_new_file ##### -->
@@ -418,11 +417,11 @@ Adds the #GIOChannel into the
 with the default priority.
 </para>
 
-@channel: a #GIOChannel.
+@channel: a #GIOChannel
-@condition: the condition to watch for.
+@condition: the condition to watch for
-@func: the function to call when the condition is satisfied.
+@func: the function to call when the condition is satisfied
-@user_data: user data to pass to @func.
+@user_data: user data to pass to @func
-@Returns: the event source id.
+@Returns: the event source id
 
 
 <!-- ##### FUNCTION g_io_add_watch_full ##### -->
@@ -432,19 +431,19 @@ Adds the #GIOChannel into the
 with the given priority.
 </para>
 
-@channel: a #GIOChannel.
+@channel: a #GIOChannel
-@priority: the priority of the #GIOChannel source.
+@priority: the priority of the #GIOChannel source
-@condition: the condition to watch for.
+@condition: the condition to watch for
-@func: the function to call when the condition is satisfied.
+@func: the function to call when the condition is satisfied
-@user_data: user data to pass to @func.
+@user_data: user data to pass to @func
-@notify: the function to call when the source is removed.
+@notify: the function to call when the source is removed
-@Returns: the event source id.
+@Returns: the event source id
 
 
 <!-- ##### ENUM GIOCondition ##### -->
 <para>
-A bitwise combination representing a condition to watch for on an event
+A bitwise combination representing a condition to watch for on 
-source.
+an event source.
 </para>
 
 @G_IO_IN: There is data to read.
@@ -458,21 +457,21 @@ source.
 <!-- ##### USER_FUNCTION GIOFunc ##### -->
 <para>
 Specifies the type of function passed to g_io_add_watch() or
-g_io_add_watch_full(), which is called when the requested condition on a
+g_io_add_watch_full(), which is called when the requested 
-#GIOChannel is satisfied.
+condition on a #GIOChannel is satisfied.
 </para>
 
-@source: the #GIOChannel event source.
+@source: the #GIOChannel event source
-@condition: the condition which has been satisfied.
+@condition: the condition which has been satisfied
-@data: user data set in g_io_add_watch() or g_io_add_watch_full().
+@data: user data set in g_io_add_watch() or g_io_add_watch_full()
-@Returns: the function should return %FALSE if the event source should be
+@Returns: the function should return %FALSE if the event source 
-removed.
+  should be removed
 
 
 <!-- ##### STRUCT GIOFuncs ##### -->
 <para>
-A table of functions used to handle different types of #GIOChannel in a
+A table of functions used to handle different types of #GIOChannel 
-generic way.
+in a generic way.
 </para>
 
 @io_read: 
@@ -538,17 +537,18 @@ be read with g_io_channel_get_flags(), but not changed with
 g_io_channel_set_flags(). 
 </para>
 
-@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND (see the 
+@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND 
-   documentation of the UNIX <function>open()</function> syscall).
+  (see the documentation of the UNIX open() syscall).
 @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to 
-   %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX 
+  %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() 
-   <function>open()</function> syscall).
+  syscall).
-@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag 
+@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. 
-   can not be changed.
+  This flag can not be changed.
-@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. This flag 
+@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable. 
-   can not be changed.
+  This flag can not be changed.
-@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that 
+@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, 
-   g_io_channel_seek_position() can be used on it. This flag can not be changed.
+  i.e. that g_io_channel_seek_position() can be used on it. 
+  This flag can not be changed.
 @G_IO_FLAG_MASK: 
 @G_IO_FLAG_GET_MASK: 
 @G_IO_FLAG_SET_MASK: 

docs/reference/glib/tmpl/keyfile.sgml

@@ -214,6 +214,20 @@ Flags which influence the parsing.
 @Returns: 
 
 
+<!-- ##### FUNCTION g_key_file_load_from_dirs ##### -->
+<para>
+
+</para>
+
+@key_file: 
+@file: 
+@search_dirs: 
+@full_path: 
+@flags: 
+@error: 
+@Returns: 
+
+
 <!-- ##### FUNCTION g_key_file_to_data ##### -->
 <para>
 

docs/reference/glib/tmpl/limits.sgml

@@ -2,7 +2,7 @@
 Limits of Basic Types
 
 <!-- ##### SECTION Short_Description ##### -->
-portable method of determining the limits of the standard types.
+portable method of determining the limits of the standard types
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/linked_lists_double.sgml

@@ -3,7 +3,7 @@ Doubly-Linked Lists
 
 <!-- ##### SECTION Short_Description ##### -->
 linked lists containing integer values or pointers to data, with the ability
-to iterate over the list in both directions.
+to iterate over the list in both directions
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/linked_lists_single.sgml

@@ -3,7 +3,7 @@ Singly-Linked Lists
 
 <!-- ##### SECTION Short_Description ##### -->
 linked lists containing integer values or pointers to data, limited to
-iterating over the list in one direction.
+iterating over the list in one direction
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/macros_misc.sgml

@@ -2,7 +2,7 @@
 Miscellaneous Macros
 
 <!-- ##### SECTION Short_Description ##### -->
-specialized macros which are not used often.
+specialized macros which are not used often
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -354,10 +354,9 @@ if (G_LIKELY (random () != 1))
   g_print ("not one");
 </programlisting></informalexample>
 
-@Returns: 
-@Since: 2.2
-<!-- # Unused Parameters # -->
 @expr: the expression
+@Returns: the value of @expr
+@Since: 2.2
 
 
 <!-- ##### MACRO G_UNLIKELY ##### -->
@@ -371,6 +370,7 @@ if (G_UNLIKELY (random () == 1))
 </programlisting></informalexample>
 
 @expr: the expression
+@Returns: the value of @expr
 @Since: 2.2
 
 

docs/reference/glib/tmpl/main.sgml

@@ -2,7 +2,7 @@
 The Main Event Loop
 
 <!-- ##### SECTION Short_Description ##### -->
-manages all available sources of events.
+manages all available sources of events
 
 <!-- ##### SECTION Long_Description ##### -->
   <para>

docs/reference/glib/tmpl/markup.sgml

@@ -2,7 +2,7 @@
 Simple XML Subset Parser
 
 <!-- ##### SECTION Short_Description ##### -->
-parses a subset of XML.
+parses a subset of XML
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/memory.sgml

@@ -2,7 +2,7 @@
 Memory Allocation
 
 <!-- ##### SECTION Short_Description ##### -->
-general memory-handling.
+general memory-handling
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/memory_chunks.sgml

@@ -2,7 +2,7 @@
 Memory Chunks
 
 <!-- ##### SECTION Short_Description ##### -->
-deprecated way to allocate groups of equal-sized chunks of memory.
+deprecated way to allocate groups of equal-sized chunks of memory
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/memory_slices.sgml

@@ -2,7 +2,7 @@
 Memory Slices
 
 <!-- ##### SECTION Short_Description ##### -->
-efficient way to allocate groups of equal-sized chunks of memory.
+efficient way to allocate groups of equal-sized chunks of memory
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/messages.sgml

@@ -2,7 +2,7 @@
 Message Logging
 
 <!-- ##### SECTION Short_Description ##### -->
-versatile support for logging messages with different levels of importance.
+versatile support for logging messages with different levels of importance
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/misc_utils.sgml

@@ -2,7 +2,7 @@
 Miscellaneous Utility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-a selection of portable utility functions.
+a selection of portable utility functions
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/modules.sgml

@@ -2,7 +2,7 @@
 Dynamic Loading of Modules
 
 <!-- ##### SECTION Short_Description ##### -->
-portable method for dynamically loading 'plug-ins'.
+portable method for dynamically loading 'plug-ins'
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/numerical.sgml

@@ -2,7 +2,7 @@
 Numerical Definitions
 
 <!-- ##### SECTION Short_Description ##### -->
-mathematical constants, and floating point decomposition.
+mathematical constants, and floating point decomposition
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/patterns.sgml

@@ -2,7 +2,7 @@
 Glob-style pattern matching
 
 <!-- ##### SECTION Short_Description ##### -->
-matches strings against patterns containing '*' (wildcard) and '?' (joker).
+matches strings against patterns containing '*' (wildcard) and '?' (joker)
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/quarks.sgml

@@ -2,7 +2,7 @@
 Quarks
 
 <!-- ##### SECTION Short_Description ##### -->
-a 2-way association between a string and a unique integer identifier.
+a 2-way association between a string and a unique integer identifier
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/queue.sgml

@@ -2,7 +2,7 @@
 Double-ended Queues
 
 <!-- ##### SECTION Short_Description ##### -->
-double-ended queue data structure.
+double-ended queue data structure
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/random_numbers.sgml

@@ -2,7 +2,7 @@
 Random Numbers
 
 <!-- ##### SECTION Short_Description ##### -->
-pseudo-random number generator.
+pseudo-random number generator
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/relations.sgml

@@ -2,7 +2,7 @@
 Relations and Tuples
 
 <!-- ##### SECTION Short_Description ##### -->
-tables of data which can be indexed on any number of fields.
+tables of data which can be indexed on any number of fields
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/scanner.sgml

@@ -2,7 +2,7 @@
 Lexical Scanner
 
 <!-- ##### SECTION Short_Description ##### -->
-a general purpose lexical scanner.
+a general purpose lexical scanner
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/shell.sgml

@@ -2,7 +2,7 @@
 Shell-related Utilities
 
 <!-- ##### SECTION Short_Description ##### -->
-shell-like commandline handling.
+shell-like commandline handling
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/spawn.sgml

@@ -2,7 +2,7 @@
 Spawning Processes
 
 <!-- ##### SECTION Short_Description ##### -->
-process launching with fork()/exec().
+process launching with fork()/exec()
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/string_chunks.sgml

@@ -2,7 +2,7 @@
 String Chunks
 
 <!-- ##### SECTION Short_Description ##### -->
-efficient storage of groups of strings.
+efficient storage of groups of strings
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -52,53 +52,31 @@ It should only be accessed by using the following functions.
 
 <!-- ##### FUNCTION g_string_chunk_new ##### -->
 <para>
-Creates a new #GStringChunk.
+
 </para>
 
-@size: the default size of the blocks of memory which are allocated to store
+@size: 
-the strings. If a particular string is larger than this default size, a larger
+@Returns: 
-block of memory will be allocated for it.
-@Returns: a new #GStringChunk.
 
 
 <!-- ##### FUNCTION g_string_chunk_insert ##### -->
 <para>
-Adds a copy of @string to the #GStringChunk.
+
-It returns a pointer to the new copy of the string in the #GStringChunk.
-The characters in the string can be changed, if necessary, though you
-should not change anything after the end of the string.
-</para>
-<para>
-Unlike g_string_chunk_insert_const(), this function does not check for
-duplicates. Also strings added with g_string_chunk_insert() will not be
-searched by g_string_chunk_insert_const() when looking for duplicates.
 </para>
 
-@chunk: a #GStringChunk.
+@chunk: 
-@string: the string to add.
+@string: 
-@Returns: a pointer to the copy of @string within the #GStringChunk.
+@Returns: 
 
 
 <!-- ##### FUNCTION g_string_chunk_insert_const ##### -->
 <para>
-Adds a copy of @string to the #GStringChunk, unless the same string has
+
-already been added to the #GStringChunk with g_string_chunk_insert_const().
-</para>
-<para>
-This function is useful if you need to copy a large number of strings
-but do not want to waste space storing duplicates. But you must remember
-that there may be several pointers to the same string, and so any changes
-made to the strings should be done very carefully.
-</para>
-<para>
-Note that g_string_chunk_insert_const() will not return a pointer to a string
-added with g_string_chunk_insert(), even if they do match.
 </para>
 
-@chunk: a #GStringChunk.
+@chunk: 
-@string: the string to add.
+@string: 
-@Returns: a pointer to the new or existing copy of @string within the
+@Returns: 
-#GStringChunk.
 
 
 <!-- ##### FUNCTION g_string_chunk_insert_len ##### -->
@@ -122,11 +100,9 @@ added with g_string_chunk_insert(), even if they do match.
 
 <!-- ##### FUNCTION g_string_chunk_free ##### -->
 <para>
-Frees all memory allocated by the #GStringChunk.
+
-After calling g_string_chunk_free() it is not safe to
-access any of the strings which were contained within it.
 </para>
 
-@chunk: a #GStringChunk
+@chunk: 
 
 

docs/reference/glib/tmpl/string_utils.sgml

@@ -2,7 +2,7 @@
 String Utility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-various string-related functions.
+various string-related functions
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/strings.sgml

@@ -2,13 +2,14 @@
 Strings
 
 <!-- ##### SECTION Short_Description ##### -->
-text buffers which grow automatically as text is added.
+text buffers which grow automatically as text is added
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-A #GString is similar to a standard C string, except that it grows automatically
+A #GString is similar to a standard C string, except that it grows 
-as text is appended or inserted. Also, it stores the length of the string, so
+automatically as text is appended or inserted. Also, it stores the 
-can be used for binary data with embedded nul bytes.
+length of the string, so can be used for binary data with embedded 
+nul bytes.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -25,10 +26,12 @@ The #GString struct contains the public fields of a #GString.
 </para>
 
 @str: points to the character data. It may move as text is added.
-The <structfield>str</structfield> field is nul-terminated and so 
+  The <structfield>str</structfield> field is nul-terminated and so 
-can be used as an ordinary C string.
+  can be used as an ordinary C string.
-@len: contains the length of the string, not including the terminating nul byte.
+@len: contains the length of the string, not including the 
-@allocated_len: 
+  terminating nul byte.
+@allocated_len: the number of bytes that can be stored in the
+  string before it needs to be reallocated. May be larger than @len.
 
 <!-- ##### FUNCTION g_string_new ##### -->
 <para>
@@ -220,10 +223,10 @@ can be used as an ordinary C string.
 
 </para>
 
-@string: a #GString.
+@string: 
-@pos: the position to insert the byte.
+@pos: 
-@c: the byte to insert.
+@c: 
-@Returns: the #GString.
+@Returns: 
 
 
 <!-- ##### FUNCTION g_string_insert_unichar ##### -->
@@ -247,7 +250,29 @@ can be used as an ordinary C string.
 @val: 
 @len: 
 @Returns: 
-o
+
+
+<!-- ##### FUNCTION g_string_overwrite ##### -->
+<para>
+
+</para>
+
+@string: 
+@pos: 
+@val: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_string_overwrite_len ##### -->
+<para>
+
+</para>
+
+@string: 
+@pos: 
+@val: 
+@len: 
+@Returns: 
 
 
 <!-- ##### FUNCTION g_string_erase ##### -->
@@ -318,12 +343,11 @@ o
 
 <!-- ##### FUNCTION g_string_equal ##### -->
 <para>
-Compares two strings for equality, returning %TRUE if they are equal. 
+
-For use with #GHashTable.
 </para>
 
-@v: a #GString
+@v: 
-@v2: another #GString
+@v2: 
-@Returns: %TRUE if they strings are the same length and contain the same bytes.
+@Returns: 
 
 

docs/reference/glib/tmpl/thread_pools.sgml

@@ -2,7 +2,7 @@
 Thread Pools
 
 <!-- ##### SECTION Short_Description ##### -->
-pools of threads to execute work concurrently.
+pools of threads to execute work concurrently
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/threads.sgml

@@ -4,7 +4,7 @@ Threads
 <!-- ##### SECTION Short_Description ##### -->
 
 thread abstraction; including threads, different mutexes, conditions
-and thread private data.
+and thread private data
 
 <!-- ##### SECTION Long_Description ##### -->
 

docs/reference/glib/tmpl/timers.sgml

@@ -2,8 +2,7 @@
 Timers
 
 <!-- ##### SECTION Short_Description ##### -->
-
+keep track of elapsed time
-keep track of elapsed time.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/trash_stack.sgml

@@ -2,7 +2,7 @@
 Trash Stacks
 
 <!-- ##### SECTION Short_Description ##### -->
-maintain a stack of unused allocated memory chunks.
+maintain a stack of unused allocated memory chunks
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/trees-binary.sgml

@@ -3,7 +3,7 @@ Balanced Binary Trees
 
 <!-- ##### SECTION Short_Description ##### -->
 a sorted collection of key/value pairs optimized for searching
-and traversing in order.
+and traversing in order
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/trees-nary.sgml

@@ -2,7 +2,7 @@
 N-ary Trees
 
 <!-- ##### SECTION Short_Description ##### -->
-trees of data with any number of branches.
+trees of data with any number of branches
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/type_conversion.sgml

@@ -2,8 +2,7 @@
 Type Conversion Macros
 
 <!-- ##### SECTION Short_Description ##### -->
-
+portably storing integers in pointer variables
-portably storing integers in pointer variables.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/types.sgml

@@ -2,7 +2,7 @@
 Basic Types
 
 <!-- ##### SECTION Short_Description ##### -->
-standard GLib types, defined for ease-of-use and portability.
+standard GLib types, defined for ease-of-use and portability
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -179,14 +179,12 @@ Values of this type can range from -9,223,372,036,854,775,808 to
 </para>
 
 
-<!-- ##### FUNCTION guint64 ##### -->
+<!-- ##### TYPEDEF guint64 ##### -->
 <para>
 An unsigned integer guaranteed to be 64 bits on all platforms.
 Values of this type can range from 0 to 18,446,744,073,709,551,615.
 </para>
 
-@Returns: 
-
 
 <!-- ##### MACRO G_GINT64_CONSTANT ##### -->
 <para>
@@ -241,6 +239,4 @@ A signed integer type that is used for file offsets, corresponding to the
 C99 type off64_t.
 </para>
 
-@Since: 2.14
-
 

docs/reference/glib/tmpl/unicode.sgml

@@ -2,7 +2,7 @@
 Unicode Manipulation
 
 <!-- ##### SECTION Short_Description ##### -->
-functions operating on Unicode characters and UTF-8 strings.
+functions operating on Unicode characters and UTF-8 strings
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
@@ -369,6 +369,15 @@ See <ulink url="http://www.unicode.org/unicode/reports/tr14/"
 @Returns: 
 
 
+<!-- ##### FUNCTION g_unichar_combining_class ##### -->
+<para>
+
+</para>
+
+@uc: 
+@Returns: 
+
+
 <!-- ##### FUNCTION g_unicode_canonical_ordering ##### -->
 <para>
 

docs/reference/glib/tmpl/warnings.sgml

@@ -2,7 +2,7 @@
 Message Output and Debugging Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-functions to output messages and help debug applications.
+functions to output messages and help debug applications
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

docs/reference/glib/tmpl/windows.sgml

@@ -2,7 +2,7 @@
 Windows Compatibility Functions
 
 <!-- ##### SECTION Short_Description ##### -->
-UNIX emulation on Windows.
+UNIX emulation on Windows
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>

glib/gregex.c

@@ -279,7 +279,7 @@ g_match_info_free (GMatchInfo *match_info)
 /**
  * g_match_info_next:
  * @match_info: a #GMatchInfo structure
- * @error: location to store the error occuring, or NULL to ignore errors
+ * @error: location to store the error occuring, or %NULL to ignore errors
  *
  * Scans for the next match using the same parameters of the previous
  * call to g_regex_match_full() or g_regex_match() that returned
@@ -300,6 +300,8 @@ g_match_info_next (GMatchInfo  *match_info,
   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
   g_return_val_if_fail (match_info->pos >= 0, FALSE);
 
+  gint opts = match_info->regex->match_opts | match_info->match_opts;
+ 
   match_info->matches = pcre_exec (match_info->regex->pcre_re,
 				   match_info->regex->extra,
 				   match_info->string,
@@ -328,6 +330,7 @@ g_match_info_next (GMatchInfo  *match_info,
           match_info->matches = PCRE_ERROR_NOMATCH;
 	  return FALSE;
         }
+
       match_info->pos = NEXT_CHAR (match_info->regex,
 				   &match_info->string[match_info->pos]) -
 				   match_info->string;
@@ -344,8 +347,10 @@ g_match_info_next (GMatchInfo  *match_info,
  * g_match_info_matches:
  * @match_info: a #GMatchInfo structure
  *
- * Returns: %TRUE if the previous match operation succeeded, %FALSE
+ * Returns wether the previous match operation succeeded.
- * otherwise
+ * 
+ * Returns: %TRUE if the previous match operation succeeded, 
+ *   %FALSE otherwise
  *
  * Since: 2.14
  */
@@ -361,16 +366,16 @@ g_match_info_matches (const GMatchInfo *match_info)
  * g_match_info_get_match_count:
  * @match_info: a #GMatchInfo structure
  *
- * Retrieves the number of matched substrings (including substring 0, that
+ * Retrieves the number of matched substrings (including substring 0, 
- * is the whole matched text), so 1 is returned if the pattern has no
+ * that is the whole matched text), so 1 is returned if the pattern 
- * substrings in it and 0 is returned if the match failed.
+ * has no substrings in it and 0 is returned if the match failed.
  *
- * If the last match was obtained using the DFA algorithm, that is using
+ * If the last match was obtained using the DFA algorithm, that is 
- * g_regex_match_all() or g_regex_match_all_full(), the retrieved
+ * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
  * count is not that of the number of capturing parentheses but that of
  * the number of matched substrings.
  *
- * Returns:  Number of matched substrings, or -1 if an error occurred
+ * Returns: Number of matched substrings, or -1 if an error occurred
  *
  * Since: 2.14
  */
@@ -416,15 +421,16 @@ g_match_info_get_match_count (const GMatchInfo *match_info)
  *
  * When using partial matching you cannot use g_match_info_fetch*().
  *
- * Because of the way certain internal optimizations are implemented the
+ * Because of the way certain internal optimizations are implemented 
- * partial matching algorithm cannot be used with all patterns. So repeated
+ * the partial matching algorithm cannot be used with all patterns. 
- * single characters such as "a{2,4}" and repeated single metasequences such
+ * So repeated single characters such as "a{2,4}" and repeated single 
- * as "\d+" are not permitted if the maximum number of occurrences is
+ * meta-sequences such as "\d+" are not permitted if the maximum number 
- * greater than one. Optional items such as "\d?" (where the maximum is one)
+ * of occurrences is greater than one. Optional items such as "\d?" 
- * are permitted. Quantifiers with any values are permitted after
+ * (where the maximum is one) are permitted. Quantifiers with any values 
- * parentheses, so the invalid examples above can be coded thus "(a){2,4}"
+ * are permitted after parentheses, so the invalid examples above can be 
- * and "(\d)+". If #G_REGEX_MATCH_PARTIAL is set for a pattern that does
+ * coded thus "(a){2,4}" and "(\d)+". If #G_REGEX_MATCH_PARTIAL is set 
- * not conform to the restrictions, matching functions return an error.
+ * for a pattern that does not conform to the restrictions, matching 
+ * functions return an error.
  *
  * Returns: %TRUE if the match was partial, %FALSE otherwise
  *
@@ -467,9 +473,9 @@ g_match_info_is_partial_match (const GMatchInfo *match_info)
  * Since: 2.14
  */
 gchar *
-g_match_info_expand_references (const GMatchInfo *match_info, 
+g_match_info_expand_references (const GMatchInfo  *match_info, 
-				const gchar      *string_to_expand,
+				const gchar       *string_to_expand,
-				GError          **error)
+				GError           **error)
 {
   GString *result;
   GList *list;
@@ -507,19 +513,19 @@ g_match_info_expand_references (const GMatchInfo *match_info,
  * @match_info: #GMatchInfo structure
  * @match_num: number of the sub expression
  *
- * Retrieves the text matching the @match_num<!-- -->'th capturing parentheses.
+ * Retrieves the text matching the @match_num<!-- -->'th capturing 
- * 0 is the full text of the match, 1 is the first paren set, 2 the second,
+ * parentheses. 0 is the full text of the match, 1 is the first paren 
- * and so on.
+ * set, 2 the second, and so on.
  *
- * If @match_num is a valid sub pattern but it didn't match anything (e.g.
+ * If @match_num is a valid sub pattern but it didn't match anything 
- * sub pattern 1, matching "b" against "(a)?b") then an empty string is
+ * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty 
- * returned.
+ * string is returned.
  *
  * If the match was obtained using the DFA algorithm, that is using
  * g_regex_match_all() or g_regex_match_all_full(), the retrieved
  * string is not that of a set of parentheses but that of a matched
- * substring. Substrings are matched in reverse order of length, so 0 is
+ * substring. Substrings are matched in reverse order of length, so 
- * the longest match.
+ * 0 is the longest match.
  *
  * The string is fetched from the string passed to the match function,
  * so you cannot call this function after freeing the string.
@@ -560,23 +566,23 @@ g_match_info_fetch (const GMatchInfo *match_info,
  * @start_pos: pointer to location where to store the start position
  * @end_pos: pointer to location where to store the end position
  *
- * Retrieves the position of the @match_num<!-- -->'th capturing parentheses.
+ * Retrieves the position of the @match_num<!-- -->'th capturing 
- * 0 is the full text of the match, 1 is the first paren set, 2 the second,
+ * parentheses. 0 is the full text of the match, 1 is the first 
- * and so on.
+ * paren set, 2 the second, and so on.
  *
- * If @match_num is a valid sub pattern but it didn't match anything (e.g.
+ * If @match_num is a valid sub pattern but it didn't match anything 
- * sub pattern 1, matching "b" against "(a)?b") then @start_pos and @end_pos
+ * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos 
- * are set to -1 and %TRUE is returned.
+ * and @end_pos are set to -1 and %TRUE is returned.
  *
  * If the match was obtained using the DFA algorithm, that is using
  * g_regex_match_all() or g_regex_match_all_full(), the retrieved
  * position is not that of a set of parentheses but that of a matched
- * substring. Substrings are matched in reverse order of length, so 0 is
+ * substring. Substrings are matched in reverse order of length, so 
- * the longest match.
+ * 0 is the longest match.
  *
- * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the
+ * Returns: %TRUE if the position was fetched, %FALSE otherwise. If 
- *          position cannot be fetched, @start_pos and @end_pos are left
+ *   the position cannot be fetched, @start_pos and @end_pos are left 
- *          unchanged.
+ *   unchanged
  *
  * Since: 2.14
  */
@@ -658,9 +664,9 @@ get_matched_substring_number (const GMatchInfo *match_info,
  *
  * Retrieves the text matching the capturing parentheses named @name.
  *
- * If @name is a valid sub pattern name but it didn't match anything (e.g.
+ * If @name is a valid sub pattern name but it didn't match anything 
- * sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b") then an empty
+ * (e.g. sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b") 
- * string is returned.
+ * then an empty string is returned.
  *
  * The string is fetched from the string passed to the match function,
  * so you cannot call this function after freeing the string.
@@ -697,13 +703,13 @@ g_match_info_fetch_named (const GMatchInfo *match_info,
  *
  * Retrieves the position of the capturing parentheses named @name.
  *
- * If @name is a valid sub pattern name but it didn't match anything (e.g.
+ * If @name is a valid sub pattern name but it didn't match anything 
- * sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b") then @start_pos and
+ * (e.g. sub pattern "X", matching "b" against "(?P&lt;X&gt;a)?b") 
- * @end_pos are set to -1 and %TRUE is returned.
+ * then @start_pos and @end_pos are set to -1 and %TRUE is returned.
  *
- * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the
+ * Returns: %TRUE if the position was fetched, %FALSE otherwise. If 
- *          position cannot be fetched, @start_pos and @end_pos are left
+ *   the position cannot be fetched, @start_pos and @end_pos are left
- *          unchanged.
+ *   unchanged
  *
  * Since: 2.14
  */
@@ -746,9 +752,9 @@ g_match_info_fetch_named_pos (const GMatchInfo *match_info,
  * The strings are fetched from the string passed to the match function,
  * so you cannot call this function after freeing the string.
  *
- * Returns: a %NULL-terminated array of gchar * pointers. It must be freed
+ * Returns: a %NULL-terminated array of gchar * pointers. It must be 
- *          using g_strfreev(). If the previous match failed %NULL is
+ *   freed using g_strfreev(). If the previous match failed %NULL is
- *          returned.
+ *   returned
  *
  * Since: 2.14
  */
@@ -837,11 +843,11 @@ g_regex_unref (GRegex *regex)
  * @match_options: match options for the regular expression
  * @error: return location for a #GError
  * 
- * Compiles the regular expression to an internal form, and does the initial
+ * Compiles the regular expression to an internal form, and does 
- * setup of the #GRegex structure.  
+ * the initial setup of the #GRegex structure.  
  * 
- * Returns: a #GRegex structure. Call g_regex_unref() when you are done
+ * Returns: a #GRegex structure. Call g_regex_unref() when you 
- * with it.
+ *   are done with it
  *
  * Since: 2.14
  */
@@ -916,6 +922,13 @@ g_regex_new (const gchar         *pattern,
       compile_options |= PCRE_NEWLINE_ANY;
     }
 
+  g_print ("compile opts: %x\n", compile_options);
+  if (compile_options & PCRE_UTF8)
+    g_print ("\tPCRE_UTF8\n");
+  if (compile_options & PCRE_NO_UTF8_CHECK)
+    g_print ("\tPCRE_NO_UTF8_CHECK\n");
+  if (compile_options & PCRE_NEWLINE_ANY)
+    g_print ("\tPCRE_NEWLINE_ANY\n");
   /* compile the pattern */
   re = pcre_compile (pattern, compile_options, &errmsg, &erroffset, NULL);
 
@@ -986,7 +999,7 @@ g_regex_get_pattern (const GRegex *regex)
  * in the pattern, or 0 if the pattern does not contain
  * back references.
  *
- * Returns: the number of the highest back reference.
+ * Returns: the number of the highest back reference
  *
  * Since: 2.14
  */
@@ -1007,7 +1020,7 @@ g_regex_get_max_backref (const GRegex *regex)
  *
  * Returns the number of capturing subpatterns in the pattern.
  *
- * Returns: the number of capturing subpatterns.
+ * Returns: the number of capturing subpatterns
  *
  * Since: 2.14
  */
@@ -1066,21 +1079,21 @@ g_regex_match_simple (const gchar        *pattern,
  * @regex: a #GRegex structure from g_regex_new()
  * @string: the string to scan for matches
  * @match_options: match options
- * @match_info: pointer to location where to store the #GMatchInfo, or
+ * @match_info: pointer to location where to store the #GMatchInfo, 
- * %NULL if you do not need it
+ *   or %NULL if you do not need it
  *
- * Scans for a match in string for the pattern in @regex. The @match_options
+ * Scans for a match in string for the pattern in @regex. 
- * are combined with the match options specified when the @regex structure
+ * The @match_options are combined with the match options specified 
- * was created, letting you have more flexibility in reusing #GRegex
+ * when the @regex structure was created, letting you have more 
- * structures.
+ * flexibility in reusing #GRegex structures.
  *
- * A #GMatchInfo structure, used to get information on the match, is stored
+ * A #GMatchInfo structure, used to get information on the match, 
- * in @match_info if not %NULL. Note that if @match_info is not %NULL then
+ * is stored in @match_info if not %NULL. Note that if @match_info 
- * it is created even if the function returns %FALSE, i.e. you must free it
+ * is not %NULL then it is created even if the function returns %FALSE, 
- * regardless if regular expression actually matched.
+ * i.e. you must free it regardless if regular expression actually matched.
  *
- * To retrieve all the non-overlapping matches of the pattern in string you
+ * To retrieve all the non-overlapping matches of the pattern in 
- * can use g_match_info_next().
+ * string you can use g_match_info_next().
  *
  * <informalexample><programlisting>
  * static void
@@ -1109,10 +1122,10 @@ g_regex_match_simple (const gchar        *pattern,
  * Since: 2.14
  */
 gboolean
-g_regex_match (const GRegex    *regex, 
+g_regex_match (const GRegex      *regex, 
-	       const gchar     *string, 
+	       const gchar       *string, 
-	       GRegexMatchFlags match_options,
+	       GRegexMatchFlags   match_options,
-	       GMatchInfo     **match_info)
+	       GMatchInfo       **match_info)
 {
   return g_regex_match_full (regex, string, -1, 0, match_options,
 			     match_info, NULL);
@@ -1125,30 +1138,31 @@ g_regex_match (const GRegex    *regex,
  * @string_len: the length of @string, or -1 if @string is nul-terminated
  * @start_position: starting index of the string to match
  * @match_options: match options
- * @match_info: pointer to location where to store the #GMatchInfo, or
+ * @match_info: pointer to location where to store the #GMatchInfo, 
- * %NULL if you do not need it
+ *   or %NULL if you do not need it
  * @error: location to store the error occuring, or %NULL to ignore errors
  *
- * Scans for a match in string for the pattern in @regex. The @match_options
+ * Scans for a match in string for the pattern in @regex. 
- * are combined with the match options specified when the @regex structure
+ * The @match_options are combined with the match options specified 
- * was created, letting you have more flexibility in reusing #GRegex
+ * when the @regex structure was created, letting you have more 
- * structures.
+ * flexibility in reusing #GRegex structures.
  *
- * Setting @start_position differs from just passing over a shortened string
+ * Setting @start_position differs from just passing over a shortened 
- * and  setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins
+ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
- * with any kind of lookbehind assertion, such as "\b".
+ * that begins with any kind of lookbehind assertion, such as "\b".
  *
- * A #GMatchInfo structure, used to get information on the match, is stored
+ * A #GMatchInfo structure, used to get information on the match, is 
- * in @match_info if not %NULL. Note that if @match_info is not %NULL then
+ * stored in @match_info if not %NULL. Note that if @match_info is 
- * it is created even if the function returns %FALSE, i.e. you must free it
+ * not %NULL then it is created even if the function returns %FALSE, 
- * regardless if regular expression actually matched.
+ * i.e. you must free it regardless if regular expression actually 
+ * matched.
  *
- * @string is not copied and is used in #GMatchInfo internally. If you use
+ * @string is not copied and is used in #GMatchInfo internally. If 
- * any #GMatchInfo method (except g_match_info_free()) after freeing or
+ * you use any #GMatchInfo method (except g_match_info_free()) after 
- * modifying @string then the behaviour is undefined.
+ * freeing or modifying @string then the behaviour is undefined.
  *
- * To retrieve all the non-overlapping matches of the pattern in string you
+ * To retrieve all the non-overlapping matches of the pattern in 
- * can use g_match_info_next().
+ * string you can use g_match_info_next().
  *
  * <informalexample><programlisting>
  * static void
@@ -1183,13 +1197,13 @@ g_regex_match (const GRegex    *regex,
  * Since: 2.14
  */
 gboolean
-g_regex_match_full (const GRegex    *regex,
+g_regex_match_full (const GRegex      *regex,
-		    const gchar     *string,
+		    const gchar       *string,
-		    gssize           string_len,
+		    gssize             string_len,
-		    gint             start_position,
+		    gint               start_position,
-		    GRegexMatchFlags match_options,
+		    GRegexMatchFlags   match_options,
-		    GMatchInfo     **match_info,
+		    GMatchInfo       **match_info,
-		    GError         **error)
+		    GError           **error)
 {
   GMatchInfo *info;
   gboolean match_ok;
@@ -1216,28 +1230,29 @@ g_regex_match_full (const GRegex    *regex,
  * @regex: a #GRegex structure from g_regex_new()
  * @string: the string to scan for matches
  * @match_options: match options
- * @match_info: pointer to location where to store the #GMatchInfo, or
+ * @match_info: pointer to location where to store the #GMatchInfo, 
- * %NULL if you do not need it
+ *   or %NULL if you do not need it
  *
- * Using the standard algorithm for regular expression matching only the
+ * Using the standard algorithm for regular expression matching only 
- * longest match in the string is retrieved. This function uses a
+ * the longest match in the string is retrieved. This function uses 
- * different algorithm so it can retrieve all the possible matches.
+ * a different algorithm so it can retrieve all the possible matches.
  * For more documentation see g_regex_match_all_full().
  *
- * A #GMatchInfo structure, used to get information on the match, is stored
+ * A #GMatchInfo structure, used to get information on the match, is 
- * in @match_info if not %NULL. Note that if @match_info is not %NULL then
+ * stored in @match_info if not %NULL. Note that if @match_info is 
- * it is created even if the function returns %FALSE, i.e. you must free it
+ * not %NULL then it is created even if the function returns %FALSE, 
- * regardless if regular expression actually matched.
+ * i.e. you must free it regardless if regular expression actually 
+ * matched.
  *
  * Returns: %TRUE is the string matched, %FALSE otherwise
  *
  * Since: 2.14
  */
 gboolean
-g_regex_match_all (const GRegex    *regex,
+g_regex_match_all (const GRegex      *regex,
-		   const gchar     *string,
+		   const gchar       *string,
-		   GRegexMatchFlags match_options,
+		   GRegexMatchFlags   match_options,
-		   GMatchInfo     **match_info)
+		   GMatchInfo       **match_info)
 {
   return g_regex_match_all_full (regex, string, -1, 0, match_options,
 				 match_info, NULL);
@@ -1250,54 +1265,55 @@ g_regex_match_all (const GRegex    *regex,
  * @string_len: the length of @string, or -1 if @string is nul-terminated
  * @start_position: starting index of the string to match
  * @match_options: match options
- * @match_info: pointer to location where to store the #GMatchInfo, or
+ * @match_info: pointer to location where to store the #GMatchInfo, 
- * %NULL if you do not need it
+ *   or %NULL if you do not need it
  * @error: location to store the error occuring, or %NULL to ignore errors
  *
- * Using the standard algorithm for regular expression matching only the
+ * Using the standard algorithm for regular expression matching only 
- * longest match in the string is retrieved, it is not possibile to obtain
+ * the longest match in the string is retrieved, it is not possibile 
- * all the available matches. For instance matching
+ * to obtain all the available matches. For instance matching
- * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;" you get
+ * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;" 
- * "&lt;a&gt; &lt;b&gt; &lt;c&gt;".
+ * you get "&lt;a&gt; &lt;b&gt; &lt;c&gt;".
  *
  * This function uses a different algorithm (called DFA, i.e. deterministic
  * finite automaton), so it can retrieve all the possible matches, all
  * starting at the same point in the string. For instance matching
- * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;" you
+ * "&lt;a&gt; &lt;b&gt; &lt;c&gt;" against the pattern "&lt;.*&gt;" 
- * would obtain three matches: "&lt;a&gt; &lt;b&gt; &lt;c&gt;",
+ * you would obtain three matches: "&lt;a&gt; &lt;b&gt; &lt;c&gt;",
  * "&lt;a&gt; &lt;b&gt;" and "&lt;a&gt;".
  *
  * The number of matched strings is retrieved using
- * g_match_info_get_match_count().
+ * g_match_info_get_match_count(). To obtain the matched strings and 
- * To obtain the matched strings and their position you can use,
+ * their position you can use, respectively, g_match_info_fetch() and 
- * respectively, g_match_info_fetch() and g_match_info_fetch_pos(). Note that
+ * g_match_info_fetch_pos(). Note that the strings are returned in 
- * the strings are returned in reverse order of length; that is, the longest
+ * reverse order of length; that is, the longest matching string is 
- * matching string is given first.
+ * given first.
  *
- * Note that the DFA algorithm is slower than the standard one and it is not
+ * Note that the DFA algorithm is slower than the standard one and it 
- * able to capture substrings, so backreferences do not work.
+ * is not able to capture substrings, so backreferences do not work.
  *
- * Setting @start_position differs from just passing over a shortened string
+ * Setting @start_position differs from just passing over a shortened 
- * and  setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins
+ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
- * with any kind of lookbehind assertion, such as "\b".
+ * that begins with any kind of lookbehind assertion, such as "\b".
  *
- * A #GMatchInfo structure, used to get information on the match, is stored
+ * A #GMatchInfo structure, used to get information on the match, is 
- * in @match_info if not %NULL. Note that if @match_info is not %NULL then
+ * stored in @match_info if not %NULL. Note that if @match_info is 
- * it is created even if the function returns %FALSE, i.e. you must free it
+ * not %NULL then it is created even if the function returns %FALSE, 
- * regardless if regular expression actually matched.
+ * i.e. you must free it regardless if regular expression actually 
+ * matched.
  *
  * Returns: %TRUE is the string matched, %FALSE otherwise
  *
  * Since: 2.14
  */
 gboolean
-g_regex_match_all_full (const GRegex    *regex,
+g_regex_match_all_full (const GRegex      *regex,
-			const gchar     *string,
+			const gchar       *string,
-			gssize           string_len,
+			gssize             string_len,
-			gint             start_position,
+			gint               start_position,
-			GRegexMatchFlags match_options,
+			GRegexMatchFlags   match_options,
-			GMatchInfo     **match_info,
+			GMatchInfo       **match_info,
-			GError         **error)
+			GError           **error)
 {
   GMatchInfo *info;
   gboolean done;
@@ -1363,7 +1379,8 @@ g_regex_match_all_full (const GRegex    *regex,
  *
  * Retrieves the number of the subexpression named @name.
  *
- * Returns: The number of the subexpression or -1 if @name does not exists
+ * Returns: The number of the subexpression or -1 if @name 
+ *   does not exists
  *
  * Since: 2.14
  */
@@ -1390,32 +1407,33 @@ g_regex_get_string_number (const GRegex *regex,
  * @compile_options: compile options for the regular expression
  * @match_options: match options
  *
- * Breaks the string on the pattern, and returns an array of the tokens.
+ * Breaks the string on the pattern, and returns an array of 
- * If the pattern contains capturing parentheses, then the text for each
+ * the tokens. If the pattern contains capturing parentheses, 
- * of the substrings will also be returned. If the pattern does not match
+ * then the text for each of the substrings will also be returned. 
- * anywhere in the string, then the whole string is returned as the first
+ * If the pattern does not match anywhere in the string, then the 
- * token.
+ * whole string is returned as the first token.
  *
- * This function is equivalent to g_regex_split() but it does not
+ * This function is equivalent to g_regex_split() but it does 
- * require to compile the pattern with g_regex_new(), avoiding some
+ * not require to compile the pattern with g_regex_new(), avoiding 
- * lines of code when you need just to do a split without extracting
+ * some lines of code when you need just to do a split without 
- * substrings, capture counts, and so on.
+ * extracting substrings, capture counts, and so on.
  *
  * If this function is to be called on the same @pattern more than
  * once, it's more efficient to compile the pattern once with
  * g_regex_new() and then use g_regex_split().
  *
- * As a special case, the result of splitting the empty string "" is an
+ * As a special case, the result of splitting the empty string "" 
- * empty vector, not a vector containing a single string. The reason for
+ * is an empty vector, not a vector containing a single string. 
- * this special case is that being able to represent a empty vector is
+ * The reason for this special case is that being able to represent 
- * typically more useful than consistent handling of empty elements. If
+ * a empty vector is typically more useful than consistent handling 
- * you do need to represent empty elements, you'll need to check for the
+ * of empty elements. If you do need to represent empty elements, 
- * empty string before calling this function.
+ * you'll need to check for the empty string before calling this 
+ * function.
  *
- * A pattern that can match empty strings splits @string into separate
+ * A pattern that can match empty strings splits @string into 
- * characters wherever it matches the empty string between characters.
+ * separate characters wherever it matches the empty string between 
- * For example splitting "ab c" using as a separator "\s*", you will get
+ * characters. For example splitting "ab c" using as a separator 
- * "a", "b" and "c".
+ * "\s*", you will get "a", "b" and "c".
  *
  * Returns: a %NULL-terminated gchar ** array. Free it using g_strfreev()
  *
@@ -1482,8 +1500,8 @@ g_regex_split (const GRegex     *regex,
  * @string_len: the length of @string, or -1 if @string is nul-terminated
  * @start_position: starting index of the string to match
  * @match_options: match time option flags
- * @max_tokens: the maximum number of tokens to split @string into. If this
+ * @max_tokens: the maximum number of tokens to split @string into. 
- *    is less than 1, the string is split completely
+ *   If this is less than 1, the string is split completely
  * @error: return location for a #GError
  *
  * Breaks the string on the pattern, and returns an array of the tokens.
@@ -1504,22 +1522,22 @@ g_regex_split (const GRegex     *regex,
  * For example splitting "ab c" using as a separator "\s*", you will get
  * "a", "b" and "c".
  *
- * Setting @start_position differs from just passing over a shortened string
+ * Setting @start_position differs from just passing over a shortened 
- * and  setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins
+ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
- * with any kind of lookbehind assertion, such as "\b".
+ * that begins with any kind of lookbehind assertion, such as "\b".
  *
  * Returns: a %NULL-terminated gchar ** array. Free it using g_strfreev()
  *
  * Since: 2.14
  **/
 gchar **
-g_regex_split_full (const GRegex     *regex, 
+g_regex_split_full (const GRegex      *regex, 
-		    const gchar      *string, 
+		    const gchar       *string, 
-		    gssize            string_len,
+		    gssize             string_len,
-		    gint              start_position,
+		    gint               start_position,
-		    GRegexMatchFlags  match_options,
+		    GRegexMatchFlags   match_options,
-		    gint              max_tokens,
+		    gint               max_tokens,
-		    GError          **error)
+		    GError           **error)
 {
   GError *tmp_error = NULL;
   GMatchInfo *match_info;
@@ -2116,12 +2134,12 @@ interpolation_list_needs_match (GList *list)
  * @error: location to store the error occuring, or %NULL to ignore errors
  *
  * Replaces all occurances of the pattern in @regex with the
- * replacement text. Backreferences of the form '\number' or '\g&lt;number&gt;'
+ * replacement text. Backreferences of the form '\number' or 
- * in the replacement text are interpolated by the number-th captured
+ * '\g&lt;number&gt;' in the replacement text are interpolated by the 
- * subexpression of the match, '\g&lt;name&gt;' refers to the captured subexpression
+ * number-th captured subexpression of the match, '\g&lt;name&gt;' refers 
- * with the given name. '\0' refers to the complete match, but '\0' followed
+ * to the captured subexpression with the given name. '\0' refers to the 
- * by a number is the octal representation of a character. To include a
+ * complete match, but '\0' followed by a number is the octal representation 
- * literal '\' in the replacement, write '\\'.
+ * of a character. To include a literal '\' in the replacement, write '\\'.
  * There are also escapes that changes the case of the following text:
  *
  * <variablelist>
@@ -2158,9 +2176,9 @@ interpolation_list_needs_match (GList *list)
  * passed to g_regex_new(). If you want to use not UTF-8 encoded stings
  * you can use g_regex_replace_literal().
  *
- * Setting @start_position differs from just passing over a shortened string
+ * Setting @start_position differs from just passing over a shortened 
- * and  setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins
+ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that 
- * with any kind of lookbehind assertion, such as "\b".
+ * begins with any kind of lookbehind assertion, such as "\b".
  *
  * Returns: a newly allocated string containing the replacements
  *
@@ -2231,22 +2249,23 @@ literal_replacement (const GMatchInfo *match_info,
  * replacement text. @replacement is replaced literally, to
  * include backreferences use g_regex_replace().
  *
- * Setting @start_position differs from just passing over a shortened string
+ * Setting @start_position differs from just passing over a 
- * and  setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins
+ * shortened string and setting #G_REGEX_MATCH_NOTBOL in the 
- * with any kind of lookbehind assertion, such as "\b".
+ * case of a pattern that begins with any kind of lookbehind 
+ * assertion, such as "\b".
  *
  * Returns: a newly allocated string containing the replacements
  *
  * Since: 2.14
  */
 gchar *
-g_regex_replace_literal (const GRegex    *regex,
+g_regex_replace_literal (const GRegex      *regex,
-			 const gchar     *string,
+			 const gchar       *string,
-			 gssize           string_len,
+			 gssize             string_len,
-			 gint             start_position,
+			 gint               start_position,
-			 const gchar     *replacement,
+			 const gchar       *replacement,
-			 GRegexMatchFlags match_options,
+			 GRegexMatchFlags   match_options,
-			 GError         **error)
+			 GError           **error)
 {
   g_return_val_if_fail (replacement != NULL, NULL);
   g_return_val_if_fail ((match_options & ~G_REGEX_MATCH_MASK) == 0, NULL);
@@ -2270,26 +2289,26 @@ g_regex_replace_literal (const GRegex    *regex,
  * @user_data: user data to pass to the function
  * @error: location to store the error occuring, or %NULL to ignore errors
  *
- * Replaces occurances of the pattern in regex with the output of @eval
+ * Replaces occurances of the pattern in regex with the output of 
- * for that occurance.
+ * @eval for that occurance.
  *
- * Setting @start_position differs from just passing over a shortened string
+ * Setting @start_position differs from just passing over a shortened 
- * and  setting #G_REGEX_MATCH_NOTBOL in the case of a pattern that begins
+ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern 
- * with any kind of lookbehind assertion, such as "\b".
+ * that begins with any kind of lookbehind assertion, such as "\b".
  *
  * Returns: a newly allocated string containing the replacements
  *
  * Since: 2.14
  */
 gchar *
-g_regex_replace_eval (const GRegex      *regex,
+g_regex_replace_eval (const GRegex        *regex,
-		      const gchar       *string,
+		      const gchar         *string,
-		      gssize             string_len,
+		      gssize               string_len,
-		      gint               start_position,
+		      gint                 start_position,
-		      GRegexMatchFlags   match_options,
+		      GRegexMatchFlags     match_options,
-		      GRegexEvalCallback eval,
+		      GRegexEvalCallback   eval,
-		      gpointer           user_data,
+		      gpointer             user_data,
-		      GError           **error)
+		      GError             **error)
 {
   GMatchInfo *match_info;
   GString *result;
@@ -2336,17 +2355,18 @@ g_regex_replace_eval (const GRegex      *regex,
  * g_regex_check_replacement:
  * @replacement: the replacement string
  * @has_references: location to store information about
- * references in @replacement or %NULL
+ *   references in @replacement or %NULL
  * @error: location to store error
  *
- * Checks whether @replacement is a valid replacement string (see g_regex_replace()),
+ * Checks whether @replacement is a valid replacement string 
- * i.e. that all escape sequences in it are valid.
+ * (see g_regex_replace()), i.e. that all escape sequences in 
+ * it are valid.
  *
- * If @has_references is not %NULL then @replacement is checked for
+ * If @has_references is not %NULL then @replacement is checked 
- * pattern references. For instance, replacement text 'foo\n'
+ * for pattern references. For instance, replacement text 'foo\n'
  * does not contain references and may be evaluated without information
- * about actual match, but '\0\1' (whole match followed by first subpattern)
+ * about actual match, but '\0\1' (whole match followed by first 
- * requires valid #GMatchInfo object.
+ * subpattern) requires valid #GMatchInfo object.
  *
  * Returns: whether @replacement is a valid replacement string
  *
@@ -2382,12 +2402,13 @@ g_regex_check_replacement (const gchar  *replacement,
  * @string: the string to escape
  * @length: the length of @string, or -1 if @string is nul-terminated
  *
- * Escapes the special characters used for regular expressions in @string,
+ * Escapes the special characters used for regular expressions 
- * for instance "a.b*c" becomes "a\.b\*c". This function is useful to
+ * in @string, for instance "a.b*c" becomes "a\.b\*c". This 
- * dynamically generate regular expressions.
+ * function is useful to dynamically generate regular expressions.
  *
- * @string can contain nul characters that are replaced with "\0", in this
+ * @string can contain nul characters that are replaced with "\0", 
- * case remember to specify the correct length of @string in @length.
+ * in this case remember to specify the correct length of @string 
+ * in @length.
  *
  * Returns: a newly-allocated escaped string
  *

glib/gstring.c

@@ -58,14 +58,14 @@ struct _GStringChunk
 
 /**
  * g_str_equal:
- * @v1: a key. 
+ * @v1: a key
- * @v2: a key to compare with @v1.
+ * @v2: a key to compare with @v1
  * 
  * Compares two strings for byte-by-byte equality 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.
  *
- * Returns: %TRUE if the two keys match.
+ * Returns: %TRUE if the two keys match
  */
 gboolean
 g_str_equal (gconstpointer v1,
@@ -79,13 +79,13 @@ g_str_equal (gconstpointer v1,
 
 /**
  * g_str_hash:
- * @v: a string key.
+ * @v: a string key
  *
  * Converts a string to a hash value.
- * It can be passed to g_hash_table_new() as the @hash_func parameter, 
+ * It can be passed to g_hash_table_new() as the @hash_func 
- * when using strings as keys in a #GHashTable.
+ * parameter, when using strings as keys in a #GHashTable.
  *
- * Returns: a hash value corresponding to the key.
+ * Returns: a hash value corresponding to the key
  */
 guint
 g_str_hash (gconstpointer v)
@@ -232,7 +232,7 @@ g_string_chunk_clear (GStringChunk *chunk)
  * duplicates.
  * 
  * Returns: a pointer to the copy of @string within 
- *          the #GStringChunk.
+ *          the #GStringChunk
  */
 gchar*
 g_string_chunk_insert (GStringChunk *chunk,
@@ -245,12 +245,12 @@ g_string_chunk_insert (GStringChunk *chunk,
 
 /**
  * g_string_chunk_insert_const:
- * @chunk:  a #GStringChunk
+ * @chunk: a #GStringChunk
  * @string: the string to add
  * 
- * Adds a copy of @string to the #GStringChunk, unless 
+ * Adds a copy of @string to the #GStringChunk, unless the same 
- * the same string has already been added to the #GStringChunk 
+ * string has already been added to the #GStringChunk with 
- * with g_string_chunk_insert_const().
+ * g_string_chunk_insert_const().
  * 
  * This function is useful if you need to copy a large number 
  * of strings but do not want to waste space storing duplicates. 
@@ -292,16 +292,17 @@ g_string_chunk_insert_const (GStringChunk *chunk,
  * @chunk: a #GStringChunk
  * @string: bytes to insert
  * @len: number of bytes of @string to insert, or -1 to insert a 
- *     nul-terminated string. 
+ *     nul-terminated string 
  * 
- * Adds a copy of the first @len bytes of @string to the #GStringChunk. The
+ * Adds a copy of the first @len bytes of @string to the #GStringChunk. 
- * copy is nul-terminated.
+ * The copy is nul-terminated.
  * 
  * Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @string has at least @len addressable bytes.
+ * responsibility to ensure that @string has at least @len addressable 
+ * bytes.
  *
- * The characters in the returned string can be changed, if necessary, though
+ * The characters in the returned string can be changed, if necessary, 
- * you should not change anything after the end of the string.
+ * though you should not change anything after the end of the string.
  * 
  * Return value: a pointer to the copy of @string within the #GStringChunk
  * 
@@ -362,14 +363,14 @@ g_string_maybe_expand (GString* string,
 /**
  * g_string_sized_new:
  * @dfl_size: the default size of the space allocated to 
- *            hold the string.
+ *            hold the string
  *
  * Creates a new #GString, with enough space for @dfl_size 
  * bytes. This is useful if you are going to add a lot of 
  * text to the string and don't want it to be reallocated 
  * too often.
  *
- * Returns: the new #GString.
+ * Returns: the new #GString
  */
 GString*
 g_string_sized_new (gsize dfl_size)    
@@ -388,11 +389,11 @@ g_string_sized_new (gsize dfl_size)
 
 /**
  * g_string_new:
- * @init: the initial text to copy into the string.
+ * @init: the initial text to copy into the string
  * 
  * Creates a new #GString, initialized with the given string.
  *
- * Returns: the new #GString.
+ * Returns: the new #GString
  */
 GString*
 g_string_new (const gchar *init)
@@ -416,18 +417,18 @@ g_string_new (const gchar *init)
 
 /**
  * g_string_new_len:
- * @init: initial contents of string.
+ * @init: initial contents of the string
- * @len: length of @init to use.
+ * @len: length of @init to use
  *
- * Creates a new #GString with @len bytes of the 
+ * Creates a new #GString with @len bytes of the @init buffer.  
- * @init buffer.  Because a length is provided, @init 
+ * Because a length is provided, @init need not be nul-terminated,
- * need not be nul-terminated, and can contain embedded 
+ * and can contain embedded nul bytes.
- * nul bytes.
  *
  * Since this function does not stop at nul bytes, it is the caller's
- * responsibility to ensure that @init has at least @len addressable bytes.
+ * responsibility to ensure that @init has at least @len addressable 
+ * bytes.
  *
- * Returns: a new #GString.
+ * Returns: a new #GString
  */
 GString*
 g_string_new_len (const gchar *init,
@@ -488,8 +489,8 @@ g_string_free (GString *string,
  * Compares two strings for equality, returning %TRUE if they are equal. 
  * For use with #GHashTable.
  *
- * Returns: %TRUE if they strings are the same 
+ * Returns: %TRUE if they strings are the same length and contain the 
- *          length and contain the same bytes.
+ *   same bytes
  */
 gboolean
 g_string_equal (const GString *v,
@@ -552,7 +553,7 @@ g_string_hash (const GString *str)
  * the standard strcpy() function, except that you do not 
  * have to worry about having enough space to copy the string.
  *
- * Returns: the destination #GString.
+ * Returns: @string
  */
 GString*
 g_string_assign (GString     *string,
@@ -576,11 +577,11 @@ g_string_assign (GString     *string,
 /**
  * g_string_truncate:
  * @string: a #GString
- * @len: the new size of the #GString
+ * @len: the new size of @string
  *
  * Cuts off the end of the GString, leaving the first @len bytes. 
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_truncate (GString *string,
@@ -635,10 +636,11 @@ g_string_set_size (GString *string,
  * nuls and need not be nul-terminated. If @pos is -1, 
  * bytes are inserted at the end of the string.
  *
- * Since this function does not stop at nul bytes, it is the caller's
+ * Since this function does not stop at nul bytes, it is 
- * responsibility to ensure that @val has at least @len addressable bytes.
+ * the caller's responsibility to ensure that @val has at 
+ * least @len addressable bytes.
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_insert_len (GString     *string,
@@ -713,12 +715,13 @@ g_string_insert_len (GString     *string,
 
 /**
  * g_string_append:
- * @string: a #GString.
+ * @string: a #GString
- * @val: the string to append onto the end of the #GString.
+ * @val: the string to append onto the end of @string
  * 
- * Adds a string onto the end of a #GString, expanding it if necessary.
+ * Adds a string onto the end of a #GString, expanding 
+ * it if necessary.
  *
- * Returns: the #GString.
+ * Returns: @string
  */
 GString*
 g_string_append (GString     *string,
@@ -734,16 +737,17 @@ g_string_append (GString     *string,
  * g_string_append_len:
  * @string: a #GString
  * @val: bytes to append
- * @len: number of bytes of @val to use.
+ * @len: number of bytes of @val to use
  * 
- * Appends @len bytes of @val to @string. 
+ * Appends @len bytes of @val to @string. Because @len is 
- * Because @len is provided, @val may contain 
+ * provided, @val may contain embedded nuls and need not 
- * embedded nuls and need not be nul-terminated.
+ * be nul-terminated.
  * 
- * Since this function does not stop at nul bytes, it is the caller's
+ * Since this function does not stop at nul bytes, it is 
- * responsibility to ensure that @val has at least @len addressable bytes.
+ * the caller's responsibility to ensure that @val has at 
+ * least @len addressable bytes.
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_append_len (GString	 *string,
@@ -758,12 +762,13 @@ g_string_append_len (GString	 *string,
 
 /**
  * g_string_append_c:
- * @string: a #GString.
+ * @string: a #GString
- * @c: the byte to append onto the end of the #GString.
+ * @c: the byte to append onto the end of @string
  *
- * Adds a byte onto the end of a #GString, expanding it if necessary.
+ * Adds a byte onto the end of a #GString, expanding 
+ * it if necessary.
  * 
- * Returns: the #GString.
+ * Returns: @string
  */
 #undef g_string_append_c
 GString*
@@ -797,12 +802,12 @@ g_string_append_unichar (GString  *string,
 /**
  * g_string_prepend:
  * @string: a #GString
- * @val: the string to prepend on the start of the #GString
+ * @val: the string to prepend on the start of @string
  *
  * Adds a string on to the start of a #GString, 
  * expanding it if necessary.
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_prepend (GString     *string,
@@ -824,10 +829,11 @@ g_string_prepend (GString     *string,
  * Because @len is provided, @val may contain 
  * embedded nuls and need not be nul-terminated.
  *
- * Since this function does not stop at nul bytes, it is the caller's
+ * Since this function does not stop at nul bytes, 
- * responsibility to ensure that @val has at least @len addressable bytes.
+ * it is the caller's responsibility to ensure that 
+ * @val has at least @len addressable bytes.
  *
- * Returns: the #GString passed in
+ * Returns: @string
  */
 GString*
 g_string_prepend_len (GString	  *string,
@@ -848,7 +854,7 @@ g_string_prepend_len (GString	  *string,
  * Adds a byte onto the start of a #GString, 
  * expanding it if necessary.
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_prepend_c (GString *string,
@@ -861,13 +867,13 @@ g_string_prepend_c (GString *string,
 
 /**
  * g_string_prepend_unichar:
- * @string: a #GString.
+ * @string: a #GString
- * @wc: a Unicode character.
+ * @wc: a Unicode character
  * 
  * Converts a Unicode character into UTF-8, and prepends it
  * to the string.
  * 
- * Return value: @string.
+ * Return value: @string
  **/
 GString*
 g_string_prepend_unichar (GString  *string,
@@ -887,7 +893,7 @@ g_string_prepend_unichar (GString  *string,
  * Inserts a copy of a string into a #GString, 
  * expanding it if necessary.
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_insert (GString     *string,
@@ -910,7 +916,7 @@ g_string_insert (GString     *string,
  *
  * Inserts a byte into a #GString, expanding it if necessary.
  * 
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_insert_c (GString *string,
@@ -943,7 +949,7 @@ g_string_insert_c (GString *string,
  * g_string_insert_unichar:
  * @string: a #GString
  * @pos: the position at which to insert character, or -1 to
- *       append at the end of the string.
+ *       append at the end of the string
  * @wc: a Unicode character
  * 
  * Converts a Unicode character into UTF-8, and insert it
@@ -1050,18 +1056,18 @@ g_string_overwrite (GString     *string,
  * @val: the string that will overwrite the @string starting at @pos
  * @len: the number of bytes to write from @val
  * 
- * Overwrites part of a string, lengthening it if necessary. This function
+ * Overwrites part of a string, lengthening it if necessary. 
- * will work with embedded NULLs.
+ * This function will work with embedded nuls.
  * 
  * Return value: @string
  *
  * Since: 2.14
  **/
 GString *
-g_string_overwrite_len (GString       *string,
+g_string_overwrite_len (GString     *string,
-			gsize          pos,
+			gsize        pos,
-			const gchar   *val,
+			const gchar *val,
-			gssize         len)
+			gssize       len)
 {
   gsize end;
 
@@ -1102,7 +1108,7 @@ g_string_overwrite_len (GString       *string,
  * Removes @len bytes from a #GString, starting at position @pos.
  * The rest of the #GString is shifted down to fill the gap.
  *
- * Returns: the #GString
+ * Returns: @string
  */
 GString*
 g_string_erase (GString *string,
@@ -1138,7 +1144,7 @@ g_string_erase (GString *string,
  * 
  * Return value: passed-in @string pointer, with all the upper case
  *               characters converted to lower case in place, with
- *               semantics that exactly match g_ascii_tolower.
+ *               semantics that exactly match g_ascii_tolower().
  **/
 GString*
 g_string_ascii_down (GString *string)
@@ -1169,7 +1175,7 @@ g_string_ascii_down (GString *string)
  * 
  * Return value: passed-in @string pointer, with all the lower case
  *               characters converted to upper case in place, with
- *               semantics that exactly match g_ascii_toupper.
+ *               semantics that exactly match g_ascii_toupper().
  **/
 GString*
 g_string_ascii_up (GString *string)
@@ -1200,9 +1206,9 @@ g_string_ascii_up (GString *string)
  *
  * Returns: the #GString.
  *
- * Deprecated:2.2: This function uses the locale-specific tolower() function, 
+ * Deprecated:2.2: This function uses the locale-specific 
- * which is almost never the right thing. Use g_string_ascii_down() or 
+ *   tolower() function, which is almost never the right thing. 
- * g_utf8_strdown() instead.
+ *   Use g_string_ascii_down() or g_utf8_strdown() instead.
  */
 GString*
 g_string_down (GString *string)
@@ -1232,11 +1238,11 @@ g_string_down (GString *string)
  * 
  * Converts a #GString to uppercase.
  * 
- * Return value: the #GString
+ * Return value: @string
  *
- * Deprecated:2.2: This function uses the locale-specific toupper() function, 
+ * Deprecated:2.2: This function uses the locale-specific 
- * which is almost never the right thing. Use g_string_ascii_up() or 
+ *   toupper() function, which is almost never the right thing. 
- * g_utf8_strup() instead.
+ *   Use g_string_ascii_up() or g_utf8_strup() instead.
  **/
 GString*
 g_string_up (GString *string)
@@ -1262,9 +1268,9 @@ g_string_up (GString *string)
 
 /**
  * g_string_append_vprintf:
- * @string: a #GString.
+ * @string: a #GString
- * @format: the string format. See the printf() documentation.
+ * @format: the string format. See the printf() documentation
- * @args: the list of arguments to insert in the output.
+ * @args: the list of arguments to insert in the output
  *
  * Appends a formatted string onto the end of a #GString.
  * This function is is similar to g_string_append_printf()
@@ -1275,16 +1281,16 @@ g_string_up (GString *string)
  */
 void
 g_string_append_vprintf (GString     *string,
-			 const gchar *fmt,
+			 const gchar *format,
 			 va_list      args)
 {
   gchar *buf;
   gint len;
   
   g_return_if_fail (string != NULL);
-  g_return_if_fail (fmt != NULL);
+  g_return_if_fail (format != NULL);
 
-  len = g_vasprintf (&buf, fmt, args);
+  len = g_vasprintf (&buf, format, args);
 
   if (len >= 0)
     {
@@ -1297,30 +1303,30 @@ g_string_append_vprintf (GString     *string,
 
 /**
  * g_string_vprintf:
- * @string: a #GString.
+ * @string: a #GString
- * @format: the string format. See the printf() documentation.
+ * @format: the string format. See the printf() documentation
- * @Varargs: the parameters to insert into the format string.
+ * @args: the parameters to insert into the format string
  *
- * Writes a formatted string into a #GString.  This function
+ * Writes a formatted string into a #GString. 
- * is similar to g_string_printf() except that the arguments to
+ * This function is similar to g_string_printf() except that 
- * the format string are passed as a va_list.
+ * the arguments to the format string are passed as a va_list.
  *
  * Since: 2.14
  */
 void
 g_string_vprintf (GString     *string,
-		  const gchar *fmt,
+		  const gchar *format,
 		  va_list      args)
 {
   g_string_truncate (string, 0);
-  g_string_append_vprintf (string, fmt, args);
+  g_string_append_vprintf (string, format, args);
 }
 
 /**
  * g_string_sprintf:
- * @string: a #GString.
+ * @string: a #GString
- * @format: the string format. See the sprintf() documentation.
+ * @format: the string format. See the sprintf() documentation
- * @Varargs: the parameters to insert into the format string.
+ * @Varargs: the parameters to insert into the format string
  *
  * Writes a formatted string into a #GString.
  * This is similar to the standard sprintf() function,
@@ -1333,9 +1339,9 @@ g_string_vprintf (GString     *string,
 
 /**
  * g_string_printf:
- * @string: a #GString.
+ * @string: a #GString
- * @format: the string format. See the printf() documentation.
+ * @format: the string format. See the printf() documentation
- * @Varargs: the parameters to insert into the format string.
+ * @Varargs: the parameters to insert into the format string
  *
  * Writes a formatted string into a #GString.
  * This is similar to the standard sprintf() function,
@@ -1344,52 +1350,51 @@ g_string_vprintf (GString     *string,
  * #GString are destroyed.
  */
 void
-g_string_printf (GString *string,
+g_string_printf (GString     *string,
-		 const gchar *fmt,
+		 const gchar *format,
 		 ...)
 {
   va_list args;
 
   g_string_truncate (string, 0);
 
-  va_start (args, fmt);
+  va_start (args, format);
-  g_string_append_vprintf (string, fmt, args);
+  g_string_append_vprintf (string, format, args);
   va_end (args);
 }
 
 /**
  * g_string_sprintfa:
- * @string: a #GString.
+ * @string: a #GString
- * @format: the string format. See the sprintf() documentation.
+ * @format: the string format. See the sprintf() documentation
- * @Varargs: the parameters to insert into the format string.
+ * @Varargs: the parameters to insert into the format string
  *
  * Appends a formatted string onto the end of a #GString.
  * This function is is similar to g_string_sprintf() except that
  * the text is appended to the #GString. 
  *
- * Deprecated: This function has been renamed to 
+ * Deprecated: This function has been renamed to g_string_append_printf()
- * g_string_append_printf().
  */
 
 /**
  * g_string_append_printf:
- * @string: a #GString.
+ * @string: a #GString
- * @format: the string format. See the printf() documentation.
+ * @format: the string format. See the printf() documentation
- * @Varargs: the parameters to insert into the format string.
+ * @Varargs: the parameters to insert into the format string
  *
  * Appends a formatted string onto the end of a #GString.
  * This function is is similar to g_string_printf() except 
  * that the text is appended to the #GString.
  */
 void
-g_string_append_printf (GString *string,
+g_string_append_printf (GString     *string,
-			const gchar *fmt,
+			const gchar *format,
 			...)
 {
   va_list args;
 
-  va_start (args, fmt);
+  va_start (args, format);
-  g_string_append_vprintf (string, fmt, args);
+  g_string_append_vprintf (string, format, args);
   va_end (args);
 }
 

glib/gunidecomp.c

@@ -49,11 +49,11 @@
 
 /**
  * g_unichar_combining_class:
- * @c: a Unicode character
+ * @uc: a Unicode character
  * 
  * Determines the canonical combining class of a Unicode character.
  * 
- * Return value: the combining class of the character.
+ * Return value: the combining class of the character
  *
  * Since: 2.14
  **/