Merge gtkdoc-conversion

1 files changed, 82 insertions, 49 deletions

diff --git a/libpurple/network.h b/libpurple/network.h
index ee7f8e0b3b..0de1c0cd58 100644
--- a/libpurple/network.h
+++ b/libpurple/network.h
@@ -40,16 +40,19 @@ typedef struct _PurpleNetworkListenData PurpleNetworkListenData;
 typedef void (*PurpleNetworkListenCallback) (int listenfd, gpointer data);
 
 /**
+ * purple_network_set_public_ip:
+ * @ip: The local IP address.
+ *
  * Sets the IP address of the local system in preferences.  This
  * is the IP address that should be used for incoming connections
  * (file transfer, direct IM, etc.) and should therefore be
  * publicly accessible.
- *
- * @ip: The local IP address.
  */
 void purple_network_set_public_ip(const char *ip);
 
 /**
+ * purple_network_get_public_ip:
+ *
  * Returns the IP address of the local system set in preferences.
  *
  * This returns the value set via purple_network_set_public_ip().
@@ -60,6 +63,9 @@ void purple_network_set_public_ip(const char *ip);
 const char *purple_network_get_public_ip(void);
 
 /**
+ * purple_network_get_local_system_ip:
+ * @fd: The fd to use to help figure out the IP, or else -1.
+ *
  * Returns the IP address of the local system.
  *
  * You probably want to use purple_network_get_my_ip() instead.
@@ -68,12 +74,13 @@ const char *purple_network_get_public_ip(void);
  *       function is called twice, it may be important to make a copy
  *       of the returned string.
  *
- * @fd: The fd to use to help figure out the IP, or else -1.
  * Returns: The local IP address.
  */
 const char *purple_network_get_local_system_ip(int fd);
 
 /**
+ * purple_network_get_all_local_system_ips:
+ *
  * Returns all IP addresses of the local system.
  *
  * Note: The caller must free this list.  If libpurple was built with
@@ -84,6 +91,9 @@ const char *purple_network_get_local_system_ip(int fd);
 GList *purple_network_get_all_local_system_ips(void);
 
 /**
+ * purple_network_get_my_ip:
+ * @fd: The fd to use to help figure out the IP, or -1.
+ *
  * Returns the IP address that should be used anywhere a
  * public IP addresses is needed (listening for an incoming
  * file transfer, etc).
@@ -97,12 +107,29 @@ GList *purple_network_get_all_local_system_ips(void);
  *       function is called twice, it may be important to make a copy
  *       of the returned string.
  *
- * @fd: The fd to use to help figure out the IP, or -1.
  * Returns: The local IP address to be used.
  */
 const char *purple_network_get_my_ip(int fd);
 
 /**
+ * purple_network_listen:
+ * @port: The port number to bind to.  Must be greater than 0.
+ * @socket_family: The protocol family of the socket.  This should be
+ *                      AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
+ *                      may or may not be able to accept IPv4 connections
+ *                      based on the system configuration (use
+ *                      purple_socket_speaks_ipv4 to check).  If an IPv6
+ *                      socket doesn't accept V4-mapped addresses, you will
+ *                      need a second listener to support both v4 and v6.
+ * @socket_type: The type of socket to open for listening.
+ *   This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
+ * @map_external: Should the open port be mapped externally using
+ *           NAT-PNP or UPnP?  (default should be TRUE)
+ * @cb: The callback to be invoked when the port to listen on is available.
+ *           The file descriptor of the listening socket will be specified in
+ *           this callback, or -1 if no socket could be established.
+ * @cb_data: extra data to be returned when cb is called
+ *
  * Attempts to open a listening port ONLY on the specified port number.
  * You probably want to use purple_network_listen_range() instead of this.
  * This function is useful, for example, if you wanted to write a telnet
@@ -119,7 +146,21 @@ const char *purple_network_get_my_ip(int fd);
  * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
  * addresses, a mapping is done).
  *
- * @port: The port number to bind to.  Must be greater than 0.
+ * Returns: A pointer to a data structure that can be used to cancel
+ *         the pending listener, or NULL if unable to obtain a local
+ *         socket to listen on.
+ */
+PurpleNetworkListenData *purple_network_listen(unsigned short port,
+	int socket_family, int socket_type, gboolean map_external,
+	PurpleNetworkListenCallback cb, gpointer cb_data);
+
+/**
+ * purple_network_listen_range:
+ * @start: The port number to bind to, or 0 to pick a random port.
+ *              Users are allowed to override this arg in prefs.
+ * @end: The highest possible port in the range of ports to listen on,
+ *            or 0 to pick a random port.  Users are allowed to override this
+ *            arg in prefs.
  * @socket_family: The protocol family of the socket.  This should be
  *                      AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
  *                      may or may not be able to accept IPv4 connections
@@ -136,15 +177,6 @@ const char *purple_network_get_my_ip(int fd);
  *           this callback, or -1 if no socket could be established.
  * @cb_data: extra data to be returned when cb is called
  *
- * Returns: A pointer to a data structure that can be used to cancel
- *         the pending listener, or NULL if unable to obtain a local
- *         socket to listen on.
- */
-PurpleNetworkListenData *purple_network_listen(unsigned short port,
-	int socket_family, int socket_type, gboolean map_external,
-	PurpleNetworkListenCallback cb, gpointer cb_data);
-
-/**
  * Opens a listening port selected from a range of ports.  The range of
  * ports used is chosen in the following manner:
  * If a range is specified in preferences, these values are used.
@@ -162,27 +194,6 @@ PurpleNetworkListenData *purple_network_listen(unsigned short port,
  * poking) for IPv6-only listeners (if an IPv6 socket supports v4-mapped
  * addresses, a mapping is done).
  *
- * @start: The port number to bind to, or 0 to pick a random port.
- *              Users are allowed to override this arg in prefs.
- * @end: The highest possible port in the range of ports to listen on,
- *            or 0 to pick a random port.  Users are allowed to override this
- *            arg in prefs.
- * @socket_family: The protocol family of the socket.  This should be
- *                      AF_INET for IPv4 or AF_INET6 for IPv6.  IPv6 sockets
- *                      may or may not be able to accept IPv4 connections
- *                      based on the system configuration (use
- *                      purple_socket_speaks_ipv4 to check).  If an IPv6
- *                      socket doesn't accept V4-mapped addresses, you will
- *                      need a second listener to support both v4 and v6.
- * @socket_type: The type of socket to open for listening.
- *   This will be either SOCK_STREAM for TCP or SOCK_DGRAM for UDP.
- * @map_external: Should the open port be mapped externally using
- *           NAT-PNP or UPnP?  (default should be TRUE)
- * @cb: The callback to be invoked when the port to listen on is available.
- *           The file descriptor of the listening socket will be specified in
- *           this callback, or -1 if no socket could be established.
- * @cb_data: extra data to be returned when cb is called
- *
  * Returns: A pointer to a data structure that can be used to cancel
  *         the pending listener, or NULL if unable to obtain a local
  *         socket to listen on.
@@ -193,26 +204,31 @@ PurpleNetworkListenData *purple_network_listen_range(
 	PurpleNetworkListenCallback cb, gpointer cb_data);
 
 /**
+ * purple_network_listen_cancel:
+ * @listen_data: This listener attempt will be cancelled and
+ *        the struct will be freed.
+ *
  * This can be used to cancel any in-progress listener connection
  * by passing in the return value from either purple_network_listen()
  * or purple_network_listen_range().
- *
- * @listen_data: This listener attempt will be cancelled and
- *        the struct will be freed.
  */
 void purple_network_listen_cancel(PurpleNetworkListenData *listen_data);
 
 /**
- * Gets a port number from a file descriptor.
- *
+ * purple_network_get_port_from_fd:
  * @fd: The file descriptor. This should be a tcp socket. The current
  *           implementation probably dies on anything but IPv4. Perhaps this
  *           possible bug will inspire new and valuable contributors to Purple.
+ *
+ * Gets a port number from a file descriptor.
+ *
  * Returns: The port number, in host byte order.
  */
 unsigned short purple_network_get_port_from_fd(int fd);
 
 /**
+ * purple_network_is_available:
+ *
  * Detects if there is an available network connection.
  *
  * Returns: TRUE if the network is available
@@ -220,6 +236,8 @@ unsigned short purple_network_get_port_from_fd(int fd);
 gboolean purple_network_is_available(void);
 
 /**
+ * purple_network_force_online:
+ *
  * Makes purple_network_is_available() always return %TRUE.
  *
  * This is what backs the --force-online command line argument in Pidgin,
@@ -229,6 +247,8 @@ gboolean purple_network_is_available(void);
 void purple_network_force_online(void);
 
 /**
+ * purple_network_get_handle:
+ *
  * Get the handle for the network system
  *
  * Returns: the handle to the network system
@@ -236,14 +256,17 @@ void purple_network_force_online(void);
 void *purple_network_get_handle(void);
 
 /**
+ * purple_network_set_stun_server:
+ * @stun_server: The host name of the STUN server to set
+ *
  * Update the STUN server IP given the host name
  * Will result in a DNS query being executed asynchronous
- *
- * @stun_server: The host name of the STUN server to set
  */
 void purple_network_set_stun_server(const gchar *stun_server);
 
 /**
+ * purple_network_get_stun_ip:
+ *
  * Get the IP address of the STUN server as a string representation
  *
  * Returns: the IP address
@@ -251,14 +274,17 @@ void purple_network_set_stun_server(const gchar *stun_server);
 const gchar *purple_network_get_stun_ip(void);
 
 /**
+ * purple_network_set_turn_server:
+ * @turn_server: The host name of the TURN server to set
+ *
  * Update the TURN server IP given the host name
  * Will result in a DNS query being executed asynchronous
- *
- * @turn_server: The host name of the TURN server to set
  */
 void purple_network_set_turn_server(const gchar *turn_server);
 
 /**
+ * purple_network_get_turn_ip:
+ *
  * Get the IP address of the TURN server as a string representation
  *
  * Returns: the IP address
@@ -266,13 +292,19 @@ void purple_network_set_turn_server(const gchar *turn_server);
 const gchar *purple_network_get_turn_ip(void);
 
 /**
- * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
- *
+ * purple_network_remove_port_mapping:
  * @fd: Socket to remove the port mapping for
+ *
+ * Remove a port mapping (UPnP or NAT-PMP) associated with listening socket
  */
 void purple_network_remove_port_mapping(gint fd);
 
 /**
+ * purple_network_convert_idn_to_ascii:
+ * @in:      The hostname to be converted.
+ * @out:     The output buffer where an allocated string will be returned.
+ *                The caller is responsible for freeing this.
+ *
  * Convert a UTF-8 domain name to ASCII in accordance with the IDNA
  * specification. If libpurple is compiled without IDN support, this function
  * copies the input into the output buffer.
@@ -282,20 +314,21 @@ void purple_network_remove_port_mapping(gint fd);
  *
  * In general, a buffer of about 512 bytes is the appropriate size to use.
  *
- * @in:      The hostname to be converted.
- * @out:     The output buffer where an allocated string will be returned.
- *                The caller is responsible for freeing this.
  * Returns:       0 on success, -1 if the out is NULL, or an error code
  *                that currently corresponds to the Idna_rc enum in libidn.
  */
 int purple_network_convert_idn_to_ascii(const gchar *in, gchar **out);
 
 /**
+ * purple_network_init:
+ *
  * Initializes the network subsystem.
  */
 void purple_network_init(void);
 
 /**
+ * purple_network_uninit:
+ *
  * Shuts down the network subsystem.
  */
 void purple_network_uninit(void);