[glibmm] A bunch of minor doxygen cleanups around the tree

From: Jonathon Jongsma <jjongsma src gnome org>
To: svn-commits-list gnome org
Cc:
Subject: [glibmm] A bunch of minor doxygen cleanups around the tree
Date: Mon, 4 Jan 2010 04:35:17 +0000 (UTC)
commit aa139e5a64fe8b189a20d5ce27fe7bab4899ec5e
Author: Jonathon Jongsma <jonathon quotidian org>
Date:   Sun Jan 3 22:34:04 2010 -0600

    A bunch of minor doxygen cleanups around the tree
    
    Mostly correct the 'since 2.24' notation on all of the network classes, and fix
    up a variety of other little issues.

 gio/src/inetaddress.hg             |    2 +-
 gio/src/inetsocketaddress.hg       |    5 +++--
 gio/src/initable.hg                |    2 +-
 gio/src/networkaddress.hg          |    2 +-
 gio/src/networkservice.hg          |    2 +-
 gio/src/resolver.hg                |    2 +-
 gio/src/socket.hg                  |   21 +++++++++------------
 gio/src/socketaddress.hg           |    2 +-
 gio/src/socketaddressenumerator.hg |    2 +-
 gio/src/socketclient.hg            |   14 +++++++++-----
 gio/src/socketconnectable.hg       |    2 +-
 gio/src/socketconnection.hg        |    6 ++----
 gio/src/socketlistener.hg          |    3 ---
 gio/src/socketservice.hg           |    3 ---
 gio/src/srvtarget.hg               |    2 +-
 gio/src/tcpconnection.hg           |    3 ---
 gio/src/threadedsocketservice.hg   |    3 ---
 gio/src/unixconnection.hg          |    5 +----
 18 files changed, 33 insertions(+), 48 deletions(-)
---
diff --git a/gio/src/inetaddress.hg b/gio/src/inetaddress.hg
index 856c3a9..1902f31 100644
--- a/gio/src/inetaddress.hg
+++ b/gio/src/inetaddress.hg
@@ -37,7 +37,7 @@ namespace Gio
  * To actually connect to a remote host, you will need a InetSocketAddress
  * (which includes a InetAddress as well as a port number).
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class InetAddress
diff --git a/gio/src/inetsocketaddress.hg b/gio/src/inetsocketaddress.hg
index de3a871..b357010 100644
--- a/gio/src/inetsocketaddress.hg
+++ b/gio/src/inetsocketaddress.hg
@@ -30,12 +30,13 @@ namespace Gio
 /** Internet SocketAddress
  *
  * An IPv4 or IPv6 socket address; that is, the combination of a
- * #GInetAddress and a port number.
+ * InetAddress and a port number.
  *
  * An IPv4 or IPv6 socket address, corresponding to a struct sockaddr_in or
  * struct sockaddr_in6.
  *
- * @newin{2,22}
+ * @newin{2,24}
+ * @ingroup NetworkIO
  */
 class InetSocketAddress
 : public SocketAddress
diff --git a/gio/src/initable.hg b/gio/src/initable.hg
index 1bcd48d..5856ff7 100644
--- a/gio/src/initable.hg
+++ b/gio/src/initable.hg
@@ -49,7 +49,7 @@ namespace Gio
  * construction and automatically initialize them, throwing an exception on
  * failure.
  *
- * @newin{2,22}
+ * @newin{2,24}
  */
 class Initable : public Glib::Interface
 {
diff --git a/gio/src/networkaddress.hg b/gio/src/networkaddress.hg
index 828665f..c2a45e4 100644
--- a/gio/src/networkaddress.hg
+++ b/gio/src/networkaddress.hg
@@ -32,7 +32,7 @@ namespace Gio
  * connect to that host, handling the possibility of multiple IP addresses and
  * multiple address families.
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class NetworkAddress : public Glib::Object,
diff --git a/gio/src/networkservice.hg b/gio/src/networkservice.hg
index 71863f8..0a16b99 100644
--- a/gio/src/networkservice.hg
+++ b/gio/src/networkservice.hg
@@ -36,7 +36,7 @@ namespace Gio
  * See SrvTarget for more information about SRV records, and see
  * SocketConnectable for and example of using the connectable interface.
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class NetworkService : public Glib::Object,
diff --git a/gio/src/resolver.hg b/gio/src/resolver.hg
index d4cf192..88bba8d 100644
--- a/gio/src/resolver.hg
+++ b/gio/src/resolver.hg
@@ -39,7 +39,7 @@ namespace Gio
  * functionality that also implement SocketConnectable, making it easy to
  * connect to a remote host/service.
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class Resolver
diff --git a/gio/src/socket.hg b/gio/src/socket.hg
index 64561b6..3f99c59 100644
--- a/gio/src/socket.hg
+++ b/gio/src/socket.hg
@@ -29,13 +29,13 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 _WRAP_ENUM(SocketType, GSocketType)
 _WRAP_ENUM(SocketProtocol, GSocketProtocol)
 _WRAP_ENUM(SocketMsgFlags, GSocketMsgFlags)
 
+/** @defgroup NetworkIO Portable Network I/O Functionality
+ */
+
 /** Low-level socket object
  *
  * A Socket is a low-level networking primitive. It is a more or less direct
@@ -48,27 +48,24 @@ _WRAP_ENUM(SocketMsgFlags, GSocketMsgFlags)
  * SocketConnection. However there may be cases where direct use of Socket is
  * useful.
  *
- * (FIXME: update this doc for giomm)
- * Socket implements the Initable interface, so if it is manually constructed by
- * e.g. g_object_new() you must call g_initable_init() and check the results
- * before using the object. This is done automatically in g_socket_new() and
- * g_socket_new_from_fd(), so these functions can return NULL.
+ * Socket implements the Initable interface, and since initialization can fail,
+ * the constructor may throw an exception.
  *
  * Sockets operate in two general modes, blocking or non-blocking. When in
  * blocking mode all operations block until the requested operation is finished
  * or there is an error. In non-blocking mode all calls that would block return
- * immediately with a G_IO_ERROR_WOULD_BLOCK error. To know when a call would
+ * immediately with a Gio::Error::WOULD_BLOCK error. To know when a call would
  * successfully run you can call condition_check(), or condition_wait(). You can
  * also use create_source() and attach it to a Glib::MainContext to get
  * callbacks when I/O is possible. Note that all sockets are always set to non
  * blocking mode in the system, and blocking mode is emulated in Socket.
  *
  * When working in non-blocking mode applications should always be able to
- * handle getting a G_IO_ERROR_WOULD_BLOCK error even when some other function
+ * handle getting a Gio::Error::WOULD_BLOCK error even when some other function
  * said that I/O was possible. This can easily happen in case of a race
  * condition in the application, but it can also happen for other reasons. For
  * instance, on Windows a socket is always seen as writable until a write
- * returns G_IO_ERROR_WOULD_BLOCK.
+ * returns Gio::Error::WOULD_BLOCK.
  *
  * Sockets can be either connection oriented or datagram based. For connection
  * oriented types you must first establish a connection by either connecting to
@@ -84,7 +81,7 @@ _WRAP_ENUM(SocketMsgFlags, GSocketMsgFlags)
  * automatically be killed if it tries to write to stdout after it has been
  * closed.
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class Socket : public Glib::Object, public Initable
diff --git a/gio/src/socketaddress.hg b/gio/src/socketaddress.hg
index 44cd5dd..02f241d 100644
--- a/gio/src/socketaddress.hg
+++ b/gio/src/socketaddress.hg
@@ -32,7 +32,7 @@ namespace Gio
 
 /** Abstract base class representing endpoints for socket communication
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class SocketAddress : public Glib::Object,
diff --git a/gio/src/socketaddressenumerator.hg b/gio/src/socketaddressenumerator.hg
index 04069fb..2651f89 100644
--- a/gio/src/socketaddressenumerator.hg
+++ b/gio/src/socketaddressenumerator.hg
@@ -31,7 +31,7 @@ class SocketAddress;
 
 /** Enumerator type for objects that contain or generate SocketAddresses
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class SocketAddressEnumerator : public Glib::Object
diff --git a/gio/src/socketclient.hg b/gio/src/socketclient.hg
index d6b7056..7021b61 100644
--- a/gio/src/socketclient.hg
+++ b/gio/src/socketclient.hg
@@ -31,18 +31,16 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * Helper for connecting to a network service
- * @see_also SocketConnection, SocketListener
+ *
+ * @see SocketConnection, SocketListener
  *
  * SocketClient is a high-level utility class for connecting to a
  * network host using a connection oriented socket type.
  *
  * You create a SocketClient object, set any options you want, then
- * call a sync or async connect operation, which returns a #GSocketConnection
+ * call a sync or async connect operation, which returns a SocketConnection
  * subclass on success.
  *
  * The type of the SocketConnection object returned depends on the type of
@@ -92,14 +90,20 @@ Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, c
 Glib::RefPtr<SocketConnection> connect_to_service(const Glib::ustring& domain, const Glib::ustring& service, std::auto_ptr<Glib::Error>& error);
 #endif //GLIBMM_EXCEPTIONS_ENABLED
 
+_IGNORE(g_socket_client_connect_async)
+_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_async)
 void connect_async(const Glib::RefPtr<SocketConnectable>& connectable, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 void connect_async(const Glib::RefPtr<SocketConnectable>& connectable, const SlotAsyncReady& slot);
 _WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_finish(const Glib::RefPtr<AsyncResult>& result), g_socket_client_connect_finish, errthrow)
 
+_IGNORE(g_socket_client_connect_to_host_async)
+_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_host_async)
 void connect_to_host_async(const Glib::ustring& host_and_port, guint16 default_port, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 void connect_to_host_async(const Glib::ustring& host_and_port, guint16 default_port, const SlotAsyncReady& slot);
 _WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_host_finish(const Glib::RefPtr<AsyncResult>& result), g_socket_client_connect_to_host_finish, errthrow)
 
+_IGNORE(g_socket_client_connect_to_service_async)
+_WRAP_METHOD_DOCS_ONLY(g_socket_client_connect_to_service_async)
 void connect_to_service_async(const Glib::ustring& domain, const Glib::ustring& service, const Glib::RefPtr<Cancellable>& cancellable, const SlotAsyncReady& slot);
 void connect_to_service_async(const Glib::ustring& domain, const Glib::ustring& service, const SlotAsyncReady& slot);
 _WRAP_METHOD(Glib::RefPtr<SocketConnection> connect_to_service_finish(const Glib::RefPtr<AsyncResult>& result), g_socket_client_connect_to_service_finish, errthrow)
diff --git a/gio/src/socketconnectable.hg b/gio/src/socketconnectable.hg
index 9e6643c..7aa3a57 100644
--- a/gio/src/socketconnectable.hg
+++ b/gio/src/socketconnectable.hg
@@ -32,7 +32,7 @@ namespace Gio
 
 /** Interface for potential socket endpoints
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class SocketConnectable : public Glib::Interface
diff --git a/gio/src/socketconnection.hg b/gio/src/socketconnection.hg
index 92016c9..9781710 100644
--- a/gio/src/socketconnection.hg
+++ b/gio/src/socketconnection.hg
@@ -28,12 +28,10 @@ _PINCLUDE(giomm/private/iostream_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * A socket connection
- * @see_also: IOStream, SocketClient, SocketListener
+ *
+ * @see IOStream, SocketClient, SocketListener
  *
  * SocketConnection is a IOStream for a connected socket. They
  * can be created either by SocketClient when connecting to a host,
diff --git a/gio/src/socketlistener.hg b/gio/src/socketlistener.hg
index 2f435d8..bfb55b1 100644
--- a/gio/src/socketlistener.hg
+++ b/gio/src/socketlistener.hg
@@ -29,9 +29,6 @@ _PINCLUDE(glibmm/private/object_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * Helper for accepting network client connections
  *
diff --git a/gio/src/socketservice.hg b/gio/src/socketservice.hg
index a6a737b..884221a 100644
--- a/gio/src/socketservice.hg
+++ b/gio/src/socketservice.hg
@@ -25,9 +25,6 @@ _PINCLUDE(giomm/private/socketlistener_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * Make it easy to implement a network service
  *
diff --git a/gio/src/srvtarget.hg b/gio/src/srvtarget.hg
index 1577b38..8700892 100644
--- a/gio/src/srvtarget.hg
+++ b/gio/src/srvtarget.hg
@@ -41,7 +41,7 @@ namespace Gio
  * planning to connect to the remote service, you can use NetworkService's
  * SocketConnectable interface and not need to worry about SrvTarget at all.
  *
- * @newin{2,22}
+ * @newin{2,24}
  * @ingroup NetworkIO
  */
 class SrvTarget
diff --git a/gio/src/tcpconnection.hg b/gio/src/tcpconnection.hg
index 44a5dcd..5f8b06c 100644
--- a/gio/src/tcpconnection.hg
+++ b/gio/src/tcpconnection.hg
@@ -26,9 +26,6 @@ _PINCLUDE(giomm/private/socketconnection_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * A TCP SocketConnection
  *
diff --git a/gio/src/threadedsocketservice.hg b/gio/src/threadedsocketservice.hg
index 234b65f..64bba1b 100644
--- a/gio/src/threadedsocketservice.hg
+++ b/gio/src/threadedsocketservice.hg
@@ -25,9 +25,6 @@ _PINCLUDE(giomm/private/socketservice_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * A threaded GSocketService
  *
diff --git a/gio/src/unixconnection.hg b/gio/src/unixconnection.hg
index 667082f..c75045e 100644
--- a/gio/src/unixconnection.hg
+++ b/gio/src/unixconnection.hg
@@ -26,13 +26,10 @@ _PINCLUDE(giomm/private/socketconnection_p.h)
 namespace Gio
 {
 
-/** @defgroup NetworkIO Portable Network I/O Functionality
- */
-
 /**
  * A Unix domain SocketConnection
  *
- * This is the subclass of #GSocketConnection that is created
+ * This is the subclass of SocketConnection that is created
  * for UNIX domain sockets.
  *
  * It contains functions to do some of the unix socket specific
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]