Fix Libproxy documentation for non-dbus generation (#98)

Co-authored-by: Jan-Michael Brummer <jan-michael.brummer1@volkswagen.de>

3 files changed, 98 insertions, 113 deletions

diff --git a/src/libproxy/proxy-dbus.c b/src/libproxy/proxy-dbus.c
index 6b594e3..57acbd9 100644
--- a/src/libproxy/proxy-dbus.c
+++ b/src/libproxy/proxy-dbus.c
@@ -28,11 +28,6 @@ struct _pxProxyFactory {
   GCancellable *cancellable;
 };
 
-/**
- * SECTION:px-proxy
- * @short_description: A convient helper for using proxy servers
- */
-
 pxProxyFactory *px_proxy_factory_copy (pxProxyFactory *self);
 
 G_DEFINE_BOXED_TYPE (pxProxyFactory,
@@ -40,24 +35,12 @@ G_DEFINE_BOXED_TYPE (pxProxyFactory,
                      (GBoxedCopyFunc)px_proxy_factory_copy,
                      (GFreeFunc)px_proxy_factory_new);
 
-
 pxProxyFactory *
 px_proxy_factory_copy (pxProxyFactory *self)
 {
   return g_memdup2 (self, sizeof (pxProxyFactory));
 }
 
-/**
- * px_proxy_factory_new:
- *
- * Creates a new `pxProxyFactory` instance.
- *
- * This instance should be kept around as long as possible as it contains
- * cached data to increase performance.  Memory usage should be minimal
- * (cache is small) and the cache lifespan is handled automatically.
- *
- * Returns: The newly created `pxProxyFactory`
- */
 pxProxyFactory *
 px_proxy_factory_new (void)
 {
@@ -93,70 +76,6 @@ px_proxy_factory_new (void)
   return self;
 }
 
-/**
- * px_proxy_factory_get_proxies:
- * @self: a #pxProxyFactory
- * @url: Get proxxies for specificed URL
- *
- * Get which proxies to use for the specified @URL.
- *
- * A %NULL-terminated array of proxy strings is returned.
- * If the first proxy fails, the second should be tried, etc...
- * Don't forget to free the strings/array when you are done.
- * If an unrecoverable error occurs, this function returns %NULL.
- *
- * Regarding performance: this method always blocks and may be called
- * in a separate thread (is thread-safe).  In most cases, the time
- * required to complete this function call is simply the time required
- * to read the configuration (i.e. from gconf, kconfig, etc).
- *
- * In the case of PAC, if no valid PAC is found in the cache (i.e.
- * configuration has changed, cache is invalid, etc), the PAC file is
- * downloaded and inserted into the cache. This is the most expensive
- * operation as the PAC is retrieved over the network. Once a PAC exists
- * in the cache, it is merely a javascript invocation to evaluate the PAC.
- * One should note that DNS can be called from within a PAC during
- * javascript invocation.
- *
- * In the case of WPAD, WPAD is used to automatically locate a PAC on the
- * network.  Currently, we only use DNS for this, but other methods may
- * be implemented in the future.  Once the PAC is located, normal PAC
- * performance (described above) applies.
- *
- * The format of the returned proxy strings are as follows:
- *
- *   - http://[username:password@]proxy:port
- *
- *   - socks://[username:password@]proxy:port
- *
- *   - socks5://[username:password@]proxy:port
- *
- *   - socks4://[username:password@]proxy:port
- *
- *   - <procotol>://[username:password@]proxy:port
- *
- *   - direct://
- *
- * Please note that the username and password in the above URLs are optional
- * and should be use to authenticate the connection if present.
- *
- * For SOCKS proxies, when the protocol version is specified (socks4:// or
- * socks5://), it is expected that only this version is used. When only
- * socks:// is set, the client MUST try SOCKS version 5 protocol and, on
- * connection failure, fallback to SOCKS version 4.
- *
- * Other proxying protocols may exist. It is expected that the returned
- * configuration scheme shall match the network service name of the
- * proxy protocol or the service name of the protocol being proxied if the
- * previous does not exist. As an example, on Mac OS X you can configure a
- * RTSP streaming proxy. The expected returned configuration would be:
- *
- *   - rtsp://[username:password@]proxy:port
- *
- * To free the returned value, call @px_proxy_factory_free_proxies.
- *
- * Returns: (transfer full): a list of proxies
- */
 char **
 px_proxy_factory_get_proxies (pxProxyFactory *self,
                               const char     *url)
@@ -209,27 +128,12 @@ px_proxy_factory_get_proxies (pxProxyFactory *self,
   return retval;
 }
 
-/**
- * px_proxy_factory_free_proxies
- * @proxies: (array zero-terminated=1): a %NULL-terminated array of proxies
- *
- * Frees the proxy array returned by @px_proxy_factory_get_proxies when no
- * longer used.
- *
- * @since 0.4.16
- */
 void
 px_proxy_factory_free_proxies (char **proxies)
 {
   g_clear_pointer (&proxies, g_strfreev);
 }
 
-/**
- * px_proxy_factory_free:
- * @self: a #pxProxyFactory
- *
- * Frees the `pxProxyFactory`.
- */
 void
 px_proxy_factory_free (pxProxyFactory *self)
 {
diff --git a/src/libproxy/proxy.c b/src/libproxy/proxy.c
index 278c0af..6cf7974 100644
--- a/src/libproxy/proxy.c
+++ b/src/libproxy/proxy.c
@@ -24,11 +24,6 @@
 #include "px-manager.h"
 #include "proxy.h"
 
-/**
- * SECTION:px-proxy
- * @short_description: A convient helper for using proxy servers
- */
-
 struct _pxProxyFactory {
   PxManager *manager;
 };
@@ -40,12 +35,6 @@ G_DEFINE_BOXED_TYPE (pxProxyFactory,
                      (GBoxedCopyFunc)px_proxy_factory_copy,
                      (GFreeFunc)px_proxy_factory_new);
 
-/**
- * px_proxy_factory_new:
- * Creates a new proxy factory.
- *
- * Returns: pointer to #px_proxy_factory
- */
 pxProxyFactory *
 px_proxy_factory_new (void)
 {
@@ -82,12 +71,6 @@ px_proxy_factory_free_proxies (char **proxies)
   g_clear_pointer (&proxies, g_strfreev);
 }
 
-/**
- * px_proxy_factory_free:
- * @self: a px_proxy_factory
- *
- * Free px_proxy_factory
- */
 void
 px_proxy_factory_free (pxProxyFactory *self)
 {
diff --git a/src/libproxy/proxy.h b/src/libproxy/proxy.h
index 50f9944..cf4fc34 100644
--- a/src/libproxy/proxy.h
+++ b/src/libproxy/proxy.h
@@ -28,15 +28,113 @@ extern "C" {
 
 #include <gio/gio.h>
 
+/**
+ * SECTION:px-proxy
+ * @short_description: A convient helper for using proxy servers
+ */
+
 typedef struct _pxProxyFactory pxProxyFactory;
 
 #define PX_TYPE_PROXY_FACTORY (px_proxy_factory_get_type ())
 
+/**
+ * px_proxy_factory_new:
+ *
+ * Creates a new `pxProxyFactory` instance.
+ *
+ * This instance should be kept around as long as possible as it contains
+ * cached data to increase performance.  Memory usage should be minimal
+ * (cache is small) and the cache lifespan is handled automatically.
+ *
+ * Returns: The newly created `pxProxyFactory`
+ */
 pxProxyFactory *px_proxy_factory_new (void);
+
 GType           px_proxy_factory_get_type (void) G_GNUC_CONST;
 
+/**
+ * px_proxy_factory_get_proxies:
+ * @self: a #pxProxyFactory
+ * @url: Get proxxies for specificed URL
+ *
+ * Get which proxies to use for the specified @URL.
+ *
+ * A %NULL-terminated array of proxy strings is returned.
+ * If the first proxy fails, the second should be tried, etc...
+ * Don't forget to free the strings/array when you are done.
+ * If an unrecoverable error occurs, this function returns %NULL.
+ *
+ * Regarding performance: this method always blocks and may be called
+ * in a separate thread (is thread-safe).  In most cases, the time
+ * required to complete this function call is simply the time required
+ * to read the configuration (i.e. from gconf, kconfig, etc).
+ *
+ * In the case of PAC, if no valid PAC is found in the cache (i.e.
+ * configuration has changed, cache is invalid, etc), the PAC file is
+ * downloaded and inserted into the cache. This is the most expensive
+ * operation as the PAC is retrieved over the network. Once a PAC exists
+ * in the cache, it is merely a javascript invocation to evaluate the PAC.
+ * One should note that DNS can be called from within a PAC during
+ * javascript invocation.
+ *
+ * In the case of WPAD, WPAD is used to automatically locate a PAC on the
+ * network.  Currently, we only use DNS for this, but other methods may
+ * be implemented in the future.  Once the PAC is located, normal PAC
+ * performance (described above) applies.
+ *
+ * The format of the returned proxy strings are as follows:
+ *
+ *   - http://[username:password@]proxy:port
+ *
+ *   - socks://[username:password@]proxy:port
+ *
+ *   - socks5://[username:password@]proxy:port
+ *
+ *   - socks4://[username:password@]proxy:port
+ *
+ *   - <procotol>://[username:password@]proxy:port
+ *
+ *   - direct://
+ *
+ * Please note that the username and password in the above URLs are optional
+ * and should be use to authenticate the connection if present.
+ *
+ * For SOCKS proxies, when the protocol version is specified (socks4:// or
+ * socks5://), it is expected that only this version is used. When only
+ * socks:// is set, the client MUST try SOCKS version 5 protocol and, on
+ * connection failure, fallback to SOCKS version 4.
+ *
+ * Other proxying protocols may exist. It is expected that the returned
+ * configuration scheme shall match the network service name of the
+ * proxy protocol or the service name of the protocol being proxied if the
+ * previous does not exist. As an example, on Mac OS X you can configure a
+ * RTSP streaming proxy. The expected returned configuration would be:
+ *
+ *   - rtsp://[username:password@]proxy:port
+ *
+ * To free the returned value, call @px_proxy_factory_free_proxies.
+ *
+ * Returns: (transfer full): a list of proxies
+ */
 char **px_proxy_factory_get_proxies (pxProxyFactory *self, const char *url);
+
+/**
+ * px_proxy_factory_free_proxies
+ * @proxies: (array zero-terminated=1): a %NULL-terminated array of proxies
+ *
+ * Frees the proxy array returned by @px_proxy_factory_get_proxies when no
+ * longer used.
+ *
+ * @since 0.4.16
+ */
 void px_proxy_factory_free_proxies (char **proxies);
+
+/**
+ * px_proxy_factory_free:
+ * @self: a #pxProxyFactory
+ *
+ * Frees the `pxProxyFactory`.
+ */
 void px_proxy_factory_free (pxProxyFactory *self);
 
 #ifdef __cplusplus