Update the docs for the new network APIs

This imports the network APIs into the gio reference docs, and cleans
up a bunch of gtk-doc warnings and documentation issues.

docs/reference/gio/gio-docs.xml

@@ -45,9 +45,11 @@
 
         <xi:include href="xml/ginputstream.xml"/>        
         <xi:include href="xml/goutputstream.xml"/>
+        <xi:include href="xml/giostream.xml"/>
 
         <xi:include href="xml/gfileinputstream.xml"/>
         <xi:include href="xml/gfileoutputstream.xml"/>
+        <xi:include href="xml/gfileiostream.xml"/>
 
         <xi:include href="xml/gfilterinputstream.xml"/>        
         <xi:include href="xml/gfilteroutputstream.xml"/>
@@ -90,17 +92,36 @@
     	<xi:include href="xml/gemblemedicon.xml"/>
     	<xi:include href="xml/gemblem.xml"/>
     </chapter>
+    <chapter id="failable_initialization">
+    	<title>Failable Initialization</title>
+    	<xi:include href="xml/ginitable.xml"/>
+    	<xi:include href="xml/gasyncinitable.xml"/>
+    </chapter>
     <chapter id="networking">
-    	<title>Networking</title>
+      <title>Lowlevel platform-independent network support</title>
-        <xi:include href="xml/gresolver.xml"/>
+      <xi:include href="xml/gsocket.xml"/>
       <xi:include href="xml/ginetaddress.xml"/>
       <xi:include href="xml/gsocketaddress.xml"/>
       <xi:include href="xml/ginetsocketaddress.xml"/>
       <xi:include href="xml/gunixsocketaddress.xml"/>
-        <xi:include href="xml/gsrvtarget.xml"/>
+      <xi:include href="xml/gsocketcontrolmessage.xml"/>
+      <xi:include href="xml/gunixfdmessage.xml"/>
+    </chapter>
+    <chapter id="resolver">
+      <title>DNS resolution</title>
+      <xi:include href="xml/gresolver.xml"/>
       <xi:include href="xml/gsocketconnectable.xml"/>
       <xi:include href="xml/gnetworkaddress.xml"/>
       <xi:include href="xml/gnetworkservice.xml"/>
+      <xi:include href="xml/gsrvtarget.xml"/>
+    </chapter>
+    <chapter id="highlevel-socket">
+      <title>Highlevel network functionallity</title>
+      <xi:include href="xml/gsocketclient.xml"/>
+      <xi:include href="xml/gsocketconnection.xml"/>
+      <xi:include href="xml/gsocketlistener.xml"/>
+      <xi:include href="xml/gsocketservice.xml"/>
+      <xi:include href="xml/gthreadedsocketservice.xml"/>
     </chapter>
     <chapter id="utils">
     	<title>Utilities</title>

docs/reference/gio/gio-sections.txt

@@ -1,3 +1,43 @@
+<SECTION>
+<FILE>ginitable</FILE>
+<TITLE>GInitable</TITLE>
+GInitable
+GInitableIface
+g_initable_init
+g_initable_new
+g_initable_new_valist
+g_initable_newv
+<SUBSECTION Standard>
+G_INITABLE
+G_INITABLE_GET_IFACE
+G_IS_INITABLE
+G_TYPE_INITABLE
+G_TYPE_IS_INITABLE
+<SUBSECTION Private>
+g_initable_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gasyncinitable</FILE>
+<TITLE>GAsyncInitable</TITLE>
+GAsyncInitable
+GAsyncInitableIface
+g_async_initable_init_async
+g_async_initable_init_finish
+g_async_initable_new_async
+g_async_initable_new_finish
+g_async_initable_new_valist_async
+g_async_initable_newv_async
+<SUBSECTION Standard>
+G_ASYNC_INITABLE
+G_ASYNC_INITABLE_GET_IFACE
+G_IS_ASYNC_INITABLE
+G_TYPE_ASYNC_INITABLE
+G_TYPE_IS_ASYNC_INITABLE
+<SUBSECTION Private>
+g_async_initable_get_type
+</SECTION>
+
 <SECTION>
 <FILE>gvfs</FILE>
 <TITLE>GVfs</TITLE>
@@ -125,6 +165,15 @@ g_file_replace_contents
 g_file_replace_contents_async
 g_file_replace_contents_finish
 g_file_copy_attributes
+g_file_create_readwrite
+g_file_create_readwrite_async
+g_file_create_readwrite_finish
+g_file_open_readwrite
+g_file_open_readwrite_async
+g_file_open_readwrite_finish
+g_file_replace_readwrite
+g_file_replace_readwrite_async
+g_file_replace_readwrite_finish
 <SUBSECTION Standard>
 G_FILE
 G_IS_FILE
@@ -453,6 +502,7 @@ g_emblem_new_with_origin
 g_emblem_get_icon
 g_emblem_get_origin
 <SUBSECTION Private>
+GEmblemClass
 g_emblem_get_type
 G_EMBLEM
 G_EMBLEM_CLASS
@@ -530,7 +580,6 @@ G_IS_FILTER_INPUT_STREAM_CLASS
 G_FILTER_INPUT_STREAM_GET_CLASS
 <SUBSECTION Private>
 g_filter_input_stream_get_type
-GFilterInputStreamPrivate
 </SECTION>
 
 <SECTION>
@@ -712,7 +761,6 @@ G_IS_FILTER_OUTPUT_STREAM_CLASS
 G_FILTER_OUTPUT_STREAM_GET_CLASS
 <SUBSECTION Private>
 g_filter_output_stream_get_type
-GFilterOutputStreamPrivate
 </SECTION>
 
 <SECTION>
@@ -786,7 +834,6 @@ G_DATA_OUTPUT_STREAM_GET_CLASS
 <SUBSECTION Private>
 g_data_output_stream_get_type
 GDataOutputStreamPrivate
-
 </SECTION>
 
 <SECTION>
@@ -810,6 +857,53 @@ g_unix_output_stream_get_type
 GUnixOutputStreamPrivate
 </SECTION>
 
+<SECTION>
+<FILE>giostream</FILE>
+<TITLE>GIOStream</TITLE>
+GIOStream
+g_io_stream_clear_pending
+g_io_stream_close
+g_io_stream_close_async
+g_io_stream_close_finish
+g_io_stream_get_input_stream
+g_io_stream_get_output_stream
+g_io_stream_has_pending
+g_io_stream_is_closed
+g_io_stream_set_pending
+<SUBSECTION Standard>
+GIOStreamClass
+G_IO_STREAM
+G_IO_STREAM_CLASS
+G_IO_STREAM_GET_CLASS
+G_IS_IO_STREAM
+G_IS_IO_STREAM_CLASS
+G_TYPE_IO_STREAM
+<SUBSECTION Private>
+GIOStreamPrivate
+g_io_stream_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gfileiostream</FILE>
+<TITLE>GFileIOStream</TITLE>
+GFileIOStream
+g_file_io_stream_get_etag
+g_file_io_stream_query_info
+g_file_io_stream_query_info_async
+g_file_io_stream_query_info_finish
+<SUBSECTION Standard>
+GFileIOStreamClass
+G_FILE_IO_STREAM
+G_FILE_IO_STREAM_CLASS
+G_FILE_IO_STREAM_GET_CLASS
+G_IS_FILE_IO_STREAM
+G_IS_FILE_IO_STREAM_CLASS
+G_TYPE_FILE_IO_STREAM
+<SUBSECTION Private>
+GFileIOStreamPrivate
+g_file_io_stream_get_type
+</SECTION>
+
 <SECTION>
 <FILE>gseekable</FILE>
 <TITLE>GSeekable</TITLE>
@@ -1449,8 +1543,7 @@ g_srv_target_get_hostname
 g_srv_target_get_port
 g_srv_target_get_priority
 g_srv_target_get_weight
-g_srv_target_get_expires
+g_srv_target_list_sort
-g_srv_target_array_sort
 <SUBSECTION Standard>
 G_TYPE_SRV_TARGET
 <SUBSECTION Private>
@@ -1491,8 +1584,8 @@ g_socket_connectable_get_type
 GNetworkAddress
 g_network_address_new
 g_network_address_get_hostname
-g_network_address_get_ascii_name
 g_network_address_get_port
+g_network_address_parse
 <SUBSECTION Standard>
 GNetworkAddressClass
 GNetworkAddressPrivate
@@ -1514,7 +1607,6 @@ g_network_service_new
 g_network_service_get_service
 g_network_service_get_protocol
 g_network_service_get_domain
-g_network_service_get_expires
 <SUBSECTION Standard>
 GNetworkServiceClass
 GNetworkServicePrivate
@@ -1527,3 +1619,247 @@ G_TYPE_NETWORK_SERVICE
 <SUBSECTION Private>
 g_network_service_get_type
 </SECTION>
+
+<SECTION>
+<FILE>gsocket</FILE>
+<TITLE>GSocket</TITLE>
+GSocket
+GSocketSourceFunc
+GSocketType
+GSocketMsgFlags
+g_socket_new
+g_socket_new_from_fd
+g_socket_bind
+g_socket_listen
+g_socket_accept
+g_socket_connect
+g_socket_check_pending_error
+g_socket_receive
+g_socket_receive_from
+g_socket_receive_message
+g_socket_send
+g_socket_send_to
+g_socket_send_message
+g_socket_close
+g_socket_is_closed
+g_socket_is_connected
+g_socket_create_source
+g_socket_condition_check
+g_socket_condition_wait
+g_socket_set_listen_backlog
+g_socket_get_listen_backlog
+g_socket_get_blocking
+g_socket_set_blocking
+g_socket_get_keepalive
+g_socket_set_keepalive
+g_socket_get_family
+g_socket_get_fd
+g_socket_get_local_address
+g_socket_get_protocol_id
+g_socket_get_protocol_name
+g_socket_get_remote_address
+g_socket_get_socket_type
+g_socket_protocol_id_lookup_by_name
+<SUBSECTION Standard>
+GSocketClass
+G_IS_SOCKET
+G_IS_SOCKET_CLASS
+G_SOCKET
+G_SOCKET_CLASS
+G_TYPE_SOCKET
+G_SOCKET_GET_CLASS
+<SUBSECTION Private>
+g_socket_get_type
+GSocketPrivate
+</SECTION>
+
+<SECTION>
+<FILE>gsocketclient</FILE>
+<TITLE>GSocketClient</TITLE>
+GSocketClient
+g_socket_client_new
+g_socket_client_connect
+g_socket_client_connect_async
+g_socket_client_connect_finish
+g_socket_client_connect_to_host
+g_socket_client_connect_to_host_async
+g_socket_client_connect_to_host_finish
+g_socket_client_set_family
+g_socket_client_set_local_address
+g_socket_client_set_protocol
+g_socket_client_set_socket_type
+g_socket_client_get_family
+g_socket_client_get_local_address
+g_socket_client_get_protocol
+g_socket_client_get_socket_type
+<SUBSECTION Standard>
+GSocketClientClass
+G_IS_SOCKET_CLIENT
+G_IS_SOCKET_CLIENT_CLASS
+G_SOCKET_CLIENT
+G_SOCKET_CLIENT_CLASS
+G_SOCKET_CLIENT_GET_CLASS
+G_TYPE_SOCKET_CLIENT
+<SUBSECTION Private>
+GSocketClientPrivate
+g_socket_client_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gsocketconnection</FILE>
+<TITLE>GSocketConnection</TITLE>
+GSocketConnection
+g_socket_connection_get_local_address
+g_socket_connection_get_remote_address
+g_socket_connection_get_socket
+<SUBSECTION>
+GTcpConnection
+<SUBSECTION>
+GUnixConnection
+g_unix_connection_receive_fd
+g_unix_connection_send_fd
+<SUBSECTION>
+g_socket_connection_factory_create_connection
+g_socket_connection_factory_lookup_type
+g_socket_connection_factory_register_type
+<SUBSECTION Standard>
+GSocketConnectionClass
+G_IS_SOCKET_CONNECTION
+G_IS_SOCKET_CONNECTION_CLASS
+G_SOCKET_CONNECTION
+G_SOCKET_CONNECTION_CLASS
+G_SOCKET_CONNECTION_GET_CLASS
+G_TYPE_SOCKET_CONNECTION
+GTcpConnectionClass
+G_IS_TCP_CONNECTION
+G_IS_TCP_CONNECTION_CLASS
+G_TCP_CONNECTION
+G_TCP_CONNECTION_CLASS
+G_TCP_CONNECTION_GET_CLASS
+G_TYPE_TCP_CONNECTION
+GUnixConnectionClass
+G_IS_UNIX_CONNECTION
+G_IS_UNIX_CONNECTION_CLASS
+G_TYPE_UNIX_CONNECTION
+G_UNIX_CONNECTION
+G_UNIX_CONNECTION_CLASS
+G_UNIX_CONNECTION_GET_CLASS
+<SUBSECTION Private>
+GSocketConnectionPrivate
+g_socket_connection_get_type
+GTcpConnectionPrivate
+g_tcp_connection_get_type
+GUnixConnectionPrivate
+g_unix_connection_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gsocketcontrolmessage</FILE>
+<TITLE>GSocketControlMessage</TITLE>
+GSocketControlMessage
+g_socket_control_message_deserialize
+g_socket_control_message_get_level
+g_socket_control_message_get_msg_type
+g_socket_control_message_get_size
+g_socket_control_message_serialize
+<SUBSECTION Standard>
+GSocketControlMessageClass
+G_IS_SOCKET_CONTROL_MESSAGE
+G_IS_SOCKET_CONTROL_MESSAGE_CLASS
+G_SOCKET_CONTROL_MESSAGE
+G_SOCKET_CONTROL_MESSAGE_CLASS
+G_SOCKET_CONTROL_MESSAGE_GET_CLASS
+G_TYPE_SOCKET_CONTROL_MESSAGE
+<SUBSECTION Private>
+GSocketControlMessagePrivate
+g_socket_control_message_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gsocketlistener</FILE>
+<TITLE>GSocketListener</TITLE>
+GSocketListener
+g_socket_listener_new
+g_socket_listener_add_socket
+g_socket_listener_add_address
+g_socket_listener_add_inet_port
+g_socket_listener_accept
+g_socket_listener_accept_async
+g_socket_listener_accept_finish
+g_socket_listener_accept_socket
+g_socket_listener_accept_socket_async
+g_socket_listener_accept_socket_finish
+g_socket_listener_close
+g_socket_listener_set_backlog
+<SUBSECTION Standard>
+GSocketListenerClass
+G_IS_SOCKET_LISTENER
+G_IS_SOCKET_LISTENER_CLASS
+G_SOCKET_LISTENER
+G_SOCKET_LISTENER_CLASS
+G_SOCKET_LISTENER_GET_CLASS
+G_TYPE_SOCKET_INPUT_STREAM
+G_TYPE_SOCKET_LISTENER
+<SUBSECTION Private>
+GSocketListenerPrivate
+g_socket_listener_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gsocketservice</FILE>
+<TITLE>GSocketService</TITLE>
+GSocketService
+g_socket_service_new
+g_socket_service_start
+g_socket_service_stop
+g_socket_service_is_active
+<SUBSECTION Standard>
+GSocketServiceClass
+G_IS_SOCKET_SERVICE
+G_IS_SOCKET_SERVICE_CLASS
+G_SOCKET_SERVICE
+G_SOCKET_SERVICE_CLASS
+G_SOCKET_SERVICE_GET_CLASS
+G_TYPE_SOCKET_SERVICE
+<SUBSECTION Private>
+GSocketServicePrivate
+g_socket_service_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gthreadedsocketservice</FILE>
+<TITLE>GThreadedSocketService</TITLE>
+GThreadedSocketService
+g_threaded_socket_service_new
+<SUBSECTION Standard>
+GThreadedSocketServiceClass
+G_IS_THREADED_SOCKET_SERVICE
+G_IS_THREADED_SOCKET_SERVICE_CLASS
+G_THREADED_SOCKET_SERVICE
+G_THREADED_SOCKET_SERVICE_CLASS
+G_THREADED_SOCKET_SERVICE_GET_CLASS
+G_TYPE_THREADED_SOCKET_SERVICE
+<SUBSECTION Private>
+GThreadedSocketServicePrivate
+g_threaded_socket_service_get_type
+</SECTION>
+
+<SECTION>
+<FILE>gunixfdmessage</FILE>
+<TITLE>GUnixFDMessage</TITLE>
+GUnixFDMessage
+g_unix_fd_message_new
+g_unix_fd_message_append_fd
+g_unix_fd_message_steal_fds
+<SUBSECTION Standard>
+GUnixFDMessageClass
+G_IS_UNIX_FD_MESSAGE
+G_IS_UNIX_FD_MESSAGE_CLASS
+G_TYPE_UNIX_FD_MESSAGE
+G_UNIX_FD_MESSAGE
+G_UNIX_FD_MESSAGE_CLASS
+G_UNIX_FD_MESSAGE_GET_CLASS
+<SUBSECTION Private>
+GUnixFDMessagePrivate
+g_unix_fd_message_get_type
+</SECTION>

docs/reference/gio/gio.types

@@ -2,6 +2,7 @@ g_app_info_create_flags_get_type
 g_app_info_get_type
 g_app_launch_context_get_type
 g_ask_password_flags_get_type
+g_async_initable_get_type
 g_async_result_get_type
 g_buffered_input_stream_get_type
 g_buffered_output_stream_get_type
@@ -13,8 +14,8 @@ g_data_stream_newline_type_get_type
 g_desktop_app_info_get_type
 g_desktop_app_info_lookup_get_type
 g_drive_get_type
-g_emblemed_icon_get_type
 g_emblem_get_type
+g_emblemed_icon_get_type
 g_file_attribute_info_flags_get_type
 g_file_attribute_status_get_type
 g_file_attribute_type_get_type
@@ -25,22 +26,25 @@ g_file_get_type
 g_file_icon_get_type
 g_file_info_get_type
 g_file_input_stream_get_type
+g_file_io_stream_get_type
 g_file_monitor_event_get_type
 g_file_monitor_flags_get_type
 g_file_monitor_get_type
-g_filename_completer_get_type
 g_file_output_stream_get_type
 g_file_query_info_flags_get_type
-g_filesystem_preview_type_get_type
 g_file_type_get_type
+g_filename_completer_get_type
+g_filesystem_preview_type_get_type
 g_filter_input_stream_get_type
 g_filter_output_stream_get_type
 g_icon_get_type
 g_inet_address_get_type
 g_inet_socket_address_get_type
+g_initable_get_type
 g_input_stream_get_type
 g_io_error_enum_get_type
 g_io_module_get_type
+g_io_stream_get_type
 g_loadable_icon_get_type
 g_local_directory_monitor_get_type
 g_local_file_monitor_get_type
@@ -62,8 +66,18 @@ g_seekable_get_type
 g_simple_async_result_get_type
 g_socket_address_enumerator_get_type
 g_socket_address_get_type
+g_socket_client_get_type
 g_socket_connectable_get_type
+g_socket_connection_get_type
+g_socket_control_message_get_type
+g_socket_get_type
+g_socket_listener_get_type
+g_socket_service_get_type
+g_tcp_connection_get_type
 g_themed_icon_get_type
+g_threaded_socket_service_get_type
+g_unix_connection_get_type
+g_unix_fd_message_get_type
 g_unix_input_stream_get_type
 g_unix_mount_monitor_get_type
 g_unix_output_stream_get_type

docs/reference/gio/overview.xml

@@ -53,6 +53,10 @@
          <term>GOutputStream</term>
          <listitem><para>write data</para></listitem>
        </varlistentry>
+       <varlistentry>
+         <term>GIOStream</term>
+         <listitem><para>read and write data</para></listitem>
+       </varlistentry>
        <varlistentry>
          <term>GSeekable</term>
          <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
@@ -70,6 +74,30 @@
           <listitem><para>abstract type for file and application icons</para></listitem>
        </varlistentry>
     </variablelist>
+    There is support for network programming, including name resolution, lowlevel socket
+    APIs and highlevel client and server helper classes:
+    <variablelist>
+       <varlistentry>
+          <term>GSocket</term>
+          <listitem><para>lowlevel platform independent socket object</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GResolver</term>
+          <listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GSocketClient</term>
+          <listitem><para>high-level network client helper</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GSocketService</term>
+          <listitem><para>high-level network server helper</para></listitem>
+       </varlistentry>
+       <varlistentry>
+          <term>GSocketConnection</term>
+          <listitem><para>network connection stream</para></listitem>
+       </varlistentry>
+    </variablelist>
     Beyond these, GIO provides facilities for file monitoring,
     asynchronous I/O and filename completion. In addition to the 
     interfaces, GIO provides implementations for the local case. 

docs/reference/glib/tmpl/glib-unused.sgml

@@ -900,6 +900,73 @@ Turns the argument into a string literal by using the '#' stringizing operator.
 </para>
 
 
+<!-- ##### VARIABLE glib_binary_age ##### -->
+<para>
+This is the binary age passed to <application>libtool</application>. If 
+<application>libtool</application> means nothing to you, don't worry 
+about it. ;-)
+</para>
+
+
+<!-- ##### FUNCTION glib_check_version ##### -->
+<para>
+
+</para>
+
+@required_major: 
+@required_minor: 
+@required_micro: 
+@Returns: 
+
+<!-- ##### VARIABLE glib_interface_age ##### -->
+<para>
+This is the interface age passed to <application>libtool</application>. If 
+<application>libtool</application> means nothing to you, don't worry 
+about it. ;-)
+</para>
+
+
+<!-- ##### VARIABLE glib_major_version ##### -->
+<para>
+The major version number of the GLib library. 
+(e.g. in GLib version 1.2.5 this is 1.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GLib library you have linked against. Contrast with the
+#GLIB_MAJOR_VERSION macro, which represents the major version of the
+GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_micro_version ##### -->
+<para>
+The micro version number of the GLib library.
+(e.g. in GLib version 1.2.5 this is 5.)
+</para>
+
+<para>
+This variable is in the library, so represents the GLib library you
+have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which
+represents the micro version of the GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_minor_version ##### -->
+<para>
+The minor version number of the GLib library.
+(e.g. in GLib version 1.2.5 this is 2.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GLib library you have linked against. Contrast with the
+#GLIB_MINOR_VERSION macro, which represents the minor version of the
+GLib headers you have included.
+</para>
+
+
 <!-- ##### MACRO lseek ##### -->
 <para>
 

docs/reference/glib/tmpl/macros_misc.sgml

@@ -403,7 +403,7 @@ Since: 2.14
 
 
 
-<!-- ##### FUNCTION G_LIKELY ##### -->
+<!-- ##### MACRO G_LIKELY ##### -->
 <para>
 Hints the compiler that the expression is likely to evaluate to a true
 value. The compiler may use this information for optimizations.
@@ -413,10 +413,9 @@ if (G_LIKELY (random () != 1))
   g_print ("not one");
 </programlisting></informalexample>
 
+@expr: the expression
 @Returns: the value of @expr
 @Since: 2.2
-<!-- # Unused Parameters # -->
-@expr: the expression
 
 
 <!-- ##### MACRO G_UNLIKELY ##### -->

docs/reference/glib/tmpl/version.sgml

@@ -19,74 +19,6 @@ typically use the features described here.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### VARIABLE glib_major_version ##### -->
-<para>
-The major version number of the GLib library. 
-(e.g. in GLib version 1.2.5 this is 1.)
-</para>
-
-<para>
-This variable is in the library, so represents the
-GLib library you have linked against. Contrast with the
-#GLIB_MAJOR_VERSION macro, which represents the major version of the
-GLib headers you have included.
-</para>
-
-
-<!-- ##### VARIABLE glib_minor_version ##### -->
-<para>
-The minor version number of the GLib library.
-(e.g. in GLib version 1.2.5 this is 2.)
-</para>
-
-<para>
-This variable is in the library, so represents the
-GLib library you have linked against. Contrast with the
-#GLIB_MINOR_VERSION macro, which represents the minor version of the
-GLib headers you have included.
-</para>
-
-
-<!-- ##### VARIABLE glib_micro_version ##### -->
-<para>
-The micro version number of the GLib library.
-(e.g. in GLib version 1.2.5 this is 5.)
-</para>
-
-<para>
-This variable is in the library, so represents the GLib library you
-have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which
-represents the micro version of the GLib headers you have included.
-</para>
-
-
-<!-- ##### VARIABLE glib_binary_age ##### -->
-<para>
-This is the binary age passed to <application>libtool</application>. If 
-<application>libtool</application> means nothing to you, don't worry 
-about it. ;-)
-</para>
-
-
-<!-- ##### VARIABLE glib_interface_age ##### -->
-<para>
-This is the interface age passed to <application>libtool</application>. If 
-<application>libtool</application> means nothing to you, don't worry 
-about it. ;-)
-</para>
-
-
-<!-- ##### FUNCTION glib_check_version ##### -->
-<para>
-
-</para>
-
-@required_major: 
-@required_minor: 
-@required_micro: 
-@Returns: 
-
-
 <!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
 <para>
 The major version number of the GLib library.

gio/gasyncinitable.c

@@ -243,8 +243,9 @@ g_async_initable_real_init_finish (GAsyncInitable *initable,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @callback: a #GAsyncReadyCallback to call when the initialization is finished
  * @user_data: the data to pass to callback function
- * @first_property_name: the name of the first property, followed by
+ * @first_property_name: the name of the first property, or %NULL if no properties
- * the value, and other property value pairs, and ended by %NULL.
+ * @...:  the value if the first property, followed by and other property
+ *    value pairs, and ended by %NULL.
  *
  * Helper function for constructing #GAsyncInitiable object. This is
  * similar to g_object_new() but also initializes the object asyncronously.
@@ -313,7 +314,7 @@ g_async_initable_newv_async (GType object_type,
 }
 
 /**
- * g_async_initable_new_async:
+ * g_async_initable_new_valist_async:
  * @object_type: a #GType supporting #GAsyncInitable.
  * @first_property_name: the name of the first property, followed by
  * the value, and other property value pairs, and ended by %NULL.

gio/gfile.c

@@ -1779,7 +1779,7 @@ g_file_create_readwrite           (GFile                      *file,
 }
 
 /**
- * g_file_replace:
+ * g_file_replace_readwrite:
  * @file: input #GFile.
  * @etag: an optional <link linkend="gfile-etag">entity tag</link> for the
  *     current #GFile, or #NULL to ignore.

gio/gfile.h

@@ -132,6 +132,15 @@ typedef struct _GFileIface    		GFileIface;
  * @mount_enclosing_volume_finish: Finishes mounting a specified location.
  * @monitor_dir: Creates a #GFileMonitor for the location.
  * @monitor_file: Creates a #GFileMonitor for the location.
+ * @open_readwrite: Open file read/write. Since 2.22.
+ * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22.
+ * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22.
+ * @create_readwrite: Creates file read/write. Since 2.22.
+ * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22.
+ * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22.
+ * @replace_readwrite: Replaces file read/write. Since 2.22.
+ * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22.
+ * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22.
  *
  * An interface for writing VFS file handles.
  **/

gio/gfileenumerator.c

@@ -589,7 +589,7 @@ g_file_enumerator_set_pending (GFileEnumerator *enumerator,
  *
  * Returns: the #GFile which is being enumerated.
  *
- * Since: 2.18.
+ * Since: 2.18
  */
 GFile *
 g_file_enumerator_get_container (GFileEnumerator *enumerator)

gio/gfileiostream.c

@@ -36,7 +36,7 @@
 
 /**
  * SECTION:gfileiostream
- * @short_description: read write streams for File
+ * @short_description:  File read and write streaming operations
  * @include: gio/gio.h
  * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable
  *
@@ -49,13 +49,17 @@
  * operations. In addition to the generic g_seekable_ API,
  * GFileIOStream has its own API for seeking and positioning.
  * To find the position of a file io stream, use
- * g_file_io_stream_tell(). To find out if a file io
+ * g_file_io_stream_tell().
- * stream supports seeking, use g_file_io_stream_can_seek().
+ *
+ * To find out if a file io stream supports seeking, use g_file_io_stream_can_seek().
  * To position a file io stream, use g_file_io_stream_seek().
  * To find out if a file io stream supports truncating, use
  * g_file_io_stream_can_truncate(). To truncate a file io
  * stream, use g_file_io_stream_truncate().
  *
+ * The default implementation of all the #GFileIOStream operations
+ * and the implementation of #GSeekable just call into the same operations
+ * on the output stream.
  * Since: 2.22
  **/
 

gio/ginetsocketaddress.c

@@ -33,7 +33,7 @@
 
 /**
  * SECTION:ginetsocketaddress
- * @short_description: Internet socket addresses
+ * @short_description: Internet #GSocketAddress
  *
  * An IPv4 or IPv6 socket address; that is, the combination of a
  * #GInetAddress and a port number.

gio/ginitable.c

@@ -136,8 +136,9 @@ g_initable_init (GInitable     *initable,
  * @cancellable: optional #GCancellable object, %NULL to ignore.
  * @error: a #GError location to store the error occuring, or %NULL to
  *    ignore.
- * @first_property_name: the name of the first property, followed by
+ * @first_property_name: the name of the first property, or %NULL if no properties
- * the value, and other property value pairs, and ended by %NULL.
+ * @...:  the value if the first property, followed by and other property
+ *    value pairs, and ended by %NULL.
  *
  * Helper function for constructing #GInitiable object. This is
  * similar to g_object_new() but also initializes the object
@@ -167,7 +168,7 @@ g_initable_new (GType          object_type,
 }
 
 /**
- * g_initable_new:
+ * g_initable_newv:
  * @object_type: a #GType supporting #GInitable.
  * @n_parameters: the number of parameters in @parameters
  * @parameters: the parameters to use to construct the object

gio/gioenums.h

@@ -464,7 +464,7 @@ typedef enum {
 /**
  * GEmblemOrigin:
  * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin
- * @G_EMBLEM_ORIGIN_DEVICE: Embleme adds device-specific information
+ * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information
  * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly"
  * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future)
  *
@@ -536,6 +536,7 @@ typedef enum
 
 /**
  * GSocketMsgFlags:
+ * @G_SOCKET_MSG_NONE: No flags.
  * @G_SOCKET_MSG_OOB: Request to send/receive out of band data.
  * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue.
  * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks.
@@ -549,7 +550,7 @@ typedef enum
  */
 typedef enum
 {
-  G_SOCKET_MSG_INVALID,
+  G_SOCKET_MSG_NONE,
   G_SOCKET_MSG_OOB = GLIB_SYSDEF_MSG_OOB,
   G_SOCKET_MSG_PEEK = GLIB_SYSDEF_MSG_PEEK,
   G_SOCKET_MSG_DONTROUTE = GLIB_SYSDEF_MSG_DONTROUTE

gio/giostream.c

@@ -35,15 +35,20 @@
 G_DEFINE_TYPE (GIOStream, g_io_stream, G_TYPE_OBJECT);
 
 /**
- * SECTION:ginputstream
+ * SECTION:giostream
- * @short_description: Base class for implementing readwrite streams
+ * @short_description: Base class for implementing read/write streams
  * @include: gio/gio.h
+ * @see_also: #GInputStream, #GOutputStream
  *
  * GIOStream represents an object that has both read and write streams.
  * Generally the two streams acts as separate input and output streams,
  * but they share some common resources and state. For instance, for
  * seekable streams they may use the same position in both streams.
  *
+ * Examples of #GIOStream objects are #GSocketConnection which represents
+ * a two-way network connection, and #GFileIOStream which represent a
+ * file handle opened in read-write mode.
+ *
  * To do the actual reading and writing you need to get the substreams
  * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream().
  *

gio/giotypes.h

@@ -280,6 +280,8 @@ typedef void (*GSimpleAsyncThreadFunc) (GSimpleAsyncResult *res,
  * This is the function type of the callback used for the #GSource
  * returned by g_socket_create_source().
  *
+ * Returns: it should return FALSE if the source should be removed.
+ *
  * Since: 2.22
  */
 typedef gboolean (*GSocketSourceFunc) (GSocket *socket,

gio/gmount.c

@@ -148,7 +148,7 @@ g_mount_base_init (gpointer g_class)
       * This signal is emitted when the #GMount is about to be
       * unmounted.
       *
-      * Since: 2.22.
+      * Since: 2.22
       **/
       g_signal_new (I_("pre-unmount"),
                     G_TYPE_MOUNT,

gio/gmount.h

@@ -44,6 +44,7 @@ typedef struct _GMountIface    GMountIface;
  * @g_iface: The parent interface.
  * @changed: Changed signal that is emitted when the mount's state has changed.
  * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized.
+ * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file.
  * @get_root: Gets a #GFile to the root directory of the #GMount.
  * @get_name: Gets a string containing the name of the #GMount.
  * @get_icon: Gets a #GIcon for the #GMount.

gio/gsocket.c

@@ -57,7 +57,7 @@
 
 /**
  * SECTION:gsocket
- * @short_description: Low-level network socket handling
+ * @short_description: Low-level socket object
  * @include: gio/gio.h
  * @see_also: #GInitable
  *
@@ -2441,7 +2441,7 @@ g_socket_condition_wait (GSocket       *socket,
 }
 
 /**
- * g_socket_send_to:
+ * g_socket_send_message:
  * @socket: a #GSocket
  * @address: a #GSocketAddress, or %NULL
  * @vectors: an array of #GOutputVector structs

gio/gsocket.h

@@ -136,11 +136,6 @@ gssize                 g_socket_send_to                 (GSocket
 							 const gchar             *buffer,
 							 gsize                    size,
 							 GError                 **error);
-GSocketControlMessage *g_socket_receive_control_message (GSocket                 *socket,
-							 GError                 **error);
-gboolean               g_socket_send_control_message    (GSocket                 *socket,
-							 GSocketControlMessage   *message,
-							 GError                 **error);
 gssize                 g_socket_receive_message         (GSocket                 *socket,
 							 GSocketAddress         **address,
 							 GInputVector            *vectors,

gio/gsocketclient.c

@@ -43,7 +43,7 @@
 
 /**
  * SECTION:gsocketclient
- * @short_description: High-level client network helper
+ * @short_description: Helper for connecting to a network service
  * @include: gio/gio.h
  * @see_also: #GSocketConnection, #GSocketListener
  *
@@ -223,7 +223,7 @@ g_socket_client_set_property (GObject      *object,
 
 /**
  * g_socket_client_get_family:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  *
  * Gets the socket family of the socket client.
  *
@@ -241,7 +241,7 @@ g_socket_client_get_family (GSocketClient *client)
 
 /**
  * g_socket_client_set_family:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  * @family: a #GSocketFamily
  *
  * Sets the socket family of the socket client.
@@ -268,7 +268,7 @@ g_socket_client_set_family (GSocketClient *client,
 
 /**
  * g_socket_client_get_socket_type:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  *
  * Gets the socket type of the socket client.
  *
@@ -286,7 +286,7 @@ g_socket_client_get_socket_type (GSocketClient *client)
 
 /**
  * g_socket_client_set_socket_type:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  * @type: a #GSocketType
  *
  * Sets the socket type of the socket client.
@@ -311,7 +311,7 @@ g_socket_client_set_socket_type (GSocketClient *client,
 
 /**
  * g_socket_client_get_protocol:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  *
  * Gets the protocol name type of the socket client.
  *
@@ -329,7 +329,7 @@ g_socket_client_get_protocol (GSocketClient *client)
 
 /**
  * g_socket_client_set_protocol:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  * @protocol: a string, or %NULL
  *
  * Sets the protocol of the socket client.
@@ -355,7 +355,7 @@ g_socket_client_set_protocol (GSocketClient        *client,
 
 /**
  * g_socket_client_get_local_address:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
  *
  * Gets the local address of the socket client.
  *
@@ -373,8 +373,8 @@ g_socket_client_get_local_address (GSocketClient *client)
 
 /**
  * g_socket_client_set_local_address:
- * @socket: a #GSocket.
+ * @client: a #GSocketClient.
- * @addres: a #GSocketAddress, or %NULL
+ * @address: a #GSocketAddress, or %NULL
  *
  * Sets the local address of the socket client.
  * The sockets created by this object will bound to the
@@ -538,12 +538,11 @@ g_socket_client_connect (GSocketClient       *client,
 
 /**
  * g_socket_client_connect_to_host:
- * @client: a #GTcpClient
+ * @client: a #SocketClient
  * @host_and_port: the name and optionally port of the host to connect to
  * @default_port: the default port to connect to
  * @cancellable: a #GCancellable, or %NULL
  * @error: a pointer to a #GError, or %NULL
- * @returns: a #GSocketConnection if successful, or %NULL on error
  *
  * This is a helper function for g_socket_client_connect().
  *
@@ -771,7 +770,7 @@ g_socket_client_enumerator_callback (GObject      *object,
 }
 
 /**
- * g_socket_client_connect_to_host_async:
+ * g_socket_client_connect_async:
  * @client: a #GTcpClient
  * @connectable: a #GSocketConnectable specifying the remote address.
  * @cancellable: a #GCancellable, or %NULL

gio/gsocketclient.h

@@ -88,8 +88,8 @@ GSocketConnection *     g_socket_client_connect                         (GSocket
                                                                          GCancellable         *cancellable,
                                                                          GError              **error);
 GSocketConnection *     g_socket_client_connect_to_host                 (GSocketClient        *client,
-									 const char           *hostname,
+									 const char           *host_and_port,
-									 int                   port,
+									 int                   default_port,
                                                                          GCancellable         *cancellable,
                                                                          GError              **error);
 void                    g_socket_client_connect_async                   (GSocketClient        *client,
@@ -101,8 +101,8 @@ GSocketConnection *     g_socket_client_connect_finish                  (GSocket
                                                                          GAsyncResult         *result,
                                                                          GError              **error);
 void                    g_socket_client_connect_to_host_async           (GSocketClient        *client,
-									 const char           *hostname,
+									 const char           *host_and_port,
-									 int                   port,
+									 int                   default_port,
                                                                          GCancellable         *cancellable,
                                                                          GAsyncReadyCallback   callback,
                                                                          gpointer              user_data);

gio/gsocketconnection.c

@@ -41,7 +41,7 @@
 
 /**
  * SECTION:gsocketconnection
- * @short_description: High-level socket connection stream
+ * @short_description: A socket connection
  * @include: gio/gio.h
  * @see_also: #GIOStream, #GSocketClient, #GSocketListener
  *
@@ -113,6 +113,18 @@ g_socket_connection_get_output_stream (GIOStream *io_stream)
   return connection->priv->output_stream;
 }
 
+/**
+ * g_socket_connection_get_socket:
+ * @connection: a #GSocketConnection.
+ *
+ * Gets the underlying #GSocket object of the connection.
+ * This can be useful if you want to do something unusual on it
+ * not supported by the #GSocketConnection APIs.
+ *
+ * Returns: a #GSocketAddress or %NULL on error.
+ *
+ * Since: 2.22
+ **/
 GSocket *
 g_socket_connection_get_socket (GSocketConnection *connection)
 {
@@ -357,11 +369,10 @@ G_LOCK_DEFINE_STATIC(connection_factories);
  * @protocol: a protocol id
  *
  * Looks up the #GType to be used when creating socket connections on
- * sockets with the specified @family,@type and @protocol_id.
+ * sockets with the specified @family,@type and @protocol.
  *
  * If no type is registered, the #GSocketConnection base type is returned.
  *
- * Returns: a #GType
  * Since: 2.22
  **/
 void

gio/gsocketconnection.h

@@ -83,7 +83,7 @@ void               g_socket_connection_factory_register_type     (GType
 								  gint           protocol);
 GType              g_socket_connection_factory_lookup_type       (GSocketFamily  family,
 								  GSocketType    type,
-								  gint           protocol);
+								  gint           protocol_id);
 GSocketConnection *g_socket_connection_factory_create_connection (GSocket       *socket);
 
 G_END_DECLS

gio/gsocketlistener.c

@@ -43,7 +43,7 @@
 /**
  * SECTION: gsocketlistener
  * @title: GSocketListener
- * @short_description: a high-level helper object for server sockets
+ * @short_description: Helper for accepting network client connections
  * @see_also: #GThreadedSocketService, #GSocketService.
  *
  * A #GSocketListener is an object that keeps track of a set
@@ -166,7 +166,7 @@ g_socket_listener_init (GSocketListener *listener)
 }
 
 /**
- * g_socket_service_new:
+ * g_socket_listener_new:
  *
  * Creates a new #GSocketListener with no sockets to listen for.
  * New listeners can be added with e.g. g_socket_listener_add_address()
@@ -245,7 +245,7 @@ g_socket_listener_add_socket (GSocketListener *listener,
 }
 
 /**
- * g_socket_listener_add_socket:
+ * g_socket_listener_add_address:
  * @listener: a #GSocketListener
  * @address: a #GSocketAddres
  * @type: a #GSocketType
@@ -693,7 +693,7 @@ g_socket_listener_accept_socket_finish (GSocketListener   *listener,
 }
 
 /**
- * g_socket_listener_accept_socket_async:
+ * g_socket_listener_accept_async:
  * @listener: a #GSocketListener
  * @cancellable: a #GCancellable, or %NULL
  * @callback: a #GAsyncReadyCallback
@@ -755,7 +755,7 @@ g_socket_listener_accept_finish (GSocketListener *listener,
 }
 
 /**
- * g_socket_listener_accept_finish:
+ * g_socket_listener_set_backlog:
  * @listener: a #GSocketListener
  * @listen_backlog: an integer
  *

gio/gsocketservice.c

@@ -25,7 +25,7 @@
 /**
  * SECTION: gsocketservice
  * @title: GSocketService
- * @short_description: a high-level object representing a service
+ * @short_description: Make it easy to implement a network service
  * @see_also: #GThreadedSocketService, #GSocketListener.
  *
  * A #GSocketService is an object that represents a service that is
@@ -310,7 +310,6 @@ g_socket_service_ready (GObject      *object,
 
 /**
  * g_socket_service_new:
- * @returns: a new #GSocketService.
  *
  * Creates a new #GSocketService with no sockets to listen for.
  * New listeners can be added with e.g. g_socket_listener_add_address()

gio/gthemedicon.c

@@ -352,7 +352,7 @@ g_themed_icon_new_with_default_fallbacks (const char *iconname)
  * Gets the names of icons from within @icon.
  *
  * Returns: a list of icon names.
- **/
+ */
 const char * const *
 g_themed_icon_get_names (GThemedIcon *icon)
 {

gio/gunixconnection.c

@@ -19,7 +19,7 @@
 /**
  * SECTION: gunixconnection
  * @title: GUnixConnection
- * @short_description: a TCP #GSocketConnection
+ * @short_description: a Unix domain #GSocketConnection
  * @see_also: #GSocketConnection.
  *
  * This is the subclass of #GSocketConnection that is created

gio/gunixsocketaddress.c

@@ -33,7 +33,7 @@
 
 /**
  * SECTION:gunixsocketaddress
- * @short_description: Unix socket addresses
+ * @short_description: Unix #GSocketAddress
  *
  * Support for UNIX-domain (aka local) sockets.
  **/