gss: add gtk-doc blurbs for some functions

https://bugzilla.gnome.org/show_bug.cgi?id=702499

5 files changed, 144 insertions, 3 deletions

diff --git a/gst-streaming-server/gss-html.c b/gst-streaming-server/gss-html.c
index aec5423..0073e3e 100644
--- a/gst-streaming-server/gss-html.c
+++ b/gst-streaming-server/gss-html.c
@@ -503,6 +503,14 @@ gss_html_sanitize_url (const char *s)
   return out;
 }
 
+/**
+ * gss_html_entity_is_sane:
+ * @s: The string to check for alphanumeric characters
+ *
+ * Checks if any characters in s are not alphanumeric
+ *
+ * Return value: TRUE if all characters in S are alphanumeric, false otherwise.
+ */
 gboolean
 gss_html_entity_is_sane (const char *s)
 {
@@ -521,6 +529,14 @@ gss_html_entity_is_sane (const char *s)
   return TRUE;
 }
 
+/**
+ * gss_html_attribute_is_sane:
+ * @s: The string to check for alphanumeric characters
+ *
+ * Checks if any characters in s are not alphanumeric
+ *
+ * Return value: TRUE if all characters in S are alphanumeric, false otherwise.
+ */
 gboolean
 gss_html_attribute_is_sane (const char *s)
 {
@@ -540,6 +556,14 @@ gss_html_attribute_is_sane (const char *s)
 
 }
 
+/**
+ * gss_html_url_is_sane:
+ * @s: The string to check for alphanumeric characters
+ *
+ * Checks if any characters in s are not alphanumeric
+ *
+ * Return value: TRUE if all characters in S are alphanumeric, false otherwise.
+ */
 gboolean
 gss_html_url_is_sane (const char *s)
 {
diff --git a/gst-streaming-server/gss-program.c b/gst-streaming-server/gss-program.c
index a2ac310..ca5b051 100644
--- a/gst-streaming-server/gss-program.c
+++ b/gst-streaming-server/gss-program.c
@@ -722,6 +722,15 @@ gss_program_get_resource (GssTransaction * t)
   gss_html_footer (t);
 }
 
+/**
+ * gss_program_add_stream_table:
+ * @program: The program to fetch the streams from.
+ * @s: The string to append the streams to.
+ *
+ * This function populates the list of streams in the rendered page
+ * by iterating through the streams in the passed in program.
+ *
+ */
 void
 gss_program_add_stream_table (GssProgram * program, GString * s)
 {
diff --git a/gst-streaming-server/gss-server.c b/gst-streaming-server/gss-server.c
index d76d14b..be1162d 100644
--- a/gst-streaming-server/gss-server.c
+++ b/gst-streaming-server/gss-server.c
@@ -123,6 +123,15 @@ static const gchar *soup_method_source;
 
 static GObjectClass *parent_class;
 
+/**
+ * get_http_server:
+ * @port: The port the new server should use
+ *
+ * Create's a new libsoup server at the given port.
+ * If supported, the new server will be IPv6. If not, IPv4.
+ *
+ * Return value: The newly created server.
+ */
 static SoupServer *
 get_http_server (int port)
 {
@@ -141,6 +150,13 @@ get_http_server (int port)
   return server;
 }
 
+/**
+ * gss_server_set_http_port:
+ * @port: The port the server should use
+ * @server: The server to set the port of.
+ *
+ * Sets the http port to use for the given server.
+ */
 static void
 gss_server_set_http_port (GssServer * server, int port)
 {
@@ -895,6 +911,13 @@ gss_server_add_string_resource (GssServer * server, const char *filename,
   gss_server_add_resource_simple (server, r);
 }
 
+/**
+ * gss_server_set_server_hostname:
+ * @server: The server to set the hostname of.
+ * @hostname: The hostname to set the server to use.
+ *
+ * Set's the server's hostname and updates the url's accordingly.
+ */
 void
 gss_server_set_server_hostname (GssServer * server, const char *hostname)
 {
@@ -924,6 +947,10 @@ gss_server_set_server_hostname (GssServer * server, const char *hostname)
   }
 }
 
+/**
+ * gss_server_follow_all:
+ * This function does nothing.
+ */
 void
 gss_server_follow_all (GssProgram * program, const char *host)
 {
@@ -944,6 +971,15 @@ gss_server_add_program_simple (GssServer * server, GssProgram * program)
   }
 }
 
+/**
+ * gss_server_add_program:
+ * @server: The server to add the new program to.
+ * @program_name: The name of the new program to add.
+ *
+ * Adds a new program with the given name to the given server.
+ *
+ * Return value: The newly added GssProgram.
+ */
 GssProgram *
 gss_server_add_program (GssServer * server, const char *program_name)
 {
@@ -964,6 +1000,14 @@ gss_server_remove_program (GssServer * server, GssProgram * program)
   GSS_OBJECT_SERVER (program) = NULL;
 }
 
+/**
+ * gss_server_add_admin_resource:
+ * @server: The server to which to add the administration resource.
+ * @resource: The resource to add to the administration panel.
+ * @name: The name to use for the hyperlink to this resource.
+ *
+ * This function adds links to the appropriate resource to the administrator bar on the rendered page.
+ */
 void
 gss_server_add_module (GssServer * server, GssModule * module)
 {
@@ -1040,6 +1084,14 @@ gss_server_lookup_resource (GssServer * server, const char *path)
   return g_hash_table_lookup (server->resources, path);
 }
 
+/**
+ * gss_server_resource_callback:
+ *
+ * This is the entry point from libsoup to the gstreamer streaming server.
+ *
+ * The expected usage is that this function is given to soup_server_add_handler
+ * to handle all url patterns that match "/" (so, basically everything).
+ */
 static void
 gss_server_resource_callback (SoupServer * soupserver, SoupMessage * msg,
     const char *path, GHashTable * query, SoupClientContext * client,
diff --git a/gst-streaming-server/gss-utils.c b/gst-streaming-server/gss-utils.c
index 07e9d37..cf449c4 100644
--- a/gst-streaming-server/gss-utils.c
+++ b/gst-streaming-server/gss-utils.c
@@ -58,6 +58,10 @@ gss_utils_get_time_string (void)
   return s;
 }
 
+/**
+ * gss_utils_get_ip_address_string:
+ * The string returned by this function must be freed by the caller.
+ */
 char *
 gss_utils_get_ip_address_string (const char *interface)
 {
@@ -292,6 +296,12 @@ gss_object_param_is_secure (GObject * object, const char *property_name)
   return FALSE;
 }
 
+/**
+ * gss_uuid_create:
+ * @pointer: to allocated array of at least 16 guint8's. The contents will be overwritten.
+ *
+ * Creates a UUID in numeric form.
+ */
 void
 gss_uuid_create (guint8 * uuid)
 {
diff --git a/gst-streaming-server/gss-websocket.c b/gst-streaming-server/gss-websocket.c
index c63760a..2f985bc 100644
--- a/gst-streaming-server/gss-websocket.c
+++ b/gst-streaming-server/gss-websocket.c
@@ -174,8 +174,14 @@ gss_websocket_network_event (G_GNUC_UNUSED SoupMessage * msg,
   GST_DEBUG ("client %u network event %d", client->conn_id, event);
 }
 #endif
-
-/* Callbacks used for websocket clients */
+/**
+ * try_parse_websocket_fragment:
+ * @client: The websocket client to perform the callback on.
+ *
+ * Callbacks used for websocket clients
+ *
+ * Return value: TRUE on success, FALSE on failure.
+ */
 static gboolean
 try_parse_websocket_fragment (GssWebsocket * client)
 {
@@ -373,7 +379,15 @@ calc_websocket_challenge_reply (const gchar * key)
 
   return ret;
 }
-
+/**
+ * http_list_contains_value:
+ * @val: A comma seperated list to search through.
+ * @needle: The value to search for in val.
+ *
+ * Linear search through comma seperated list gchar * val for gchar * needle.
+ *
+ * Return value: TRUE if the list contains needle. FALSE otherwise.
+ */
 static gboolean
 http_list_contains_value (const gchar * val, const gchar * needle)
 {
@@ -393,6 +407,14 @@ http_list_contains_value (const gchar * val, const gchar * needle)
   return found_needle;
 }
 
+/**
+ * is_websocket_client:
+ * @client: The client to check.
+ *
+ * Determines if the given client is specifically a websocket client.
+ *
+ * Return value: TRUE if client is a websocket client, otherwise FALSE.
+ */
 static gboolean
 is_websocket_client (GssWebsocket * client)
 {
@@ -449,6 +471,18 @@ is_websocket_client (GssWebsocket * client)
   return TRUE;
 }
 
+/**
+ * gss_websocket_new:
+ * @soup: The soup server to create this GssWebsocket* under
+ * @msg: The message to create this GssWebsocket* for
+ * @context: The context therein.
+ *
+ * Creates and returns a new GssWebsocket*
+ * which is initialized using the passed in SoupServer*,
+ * SoupMessage*, and SoupClientContext*
+ *
+ * Return value: a GssWebsocket* pointing to a newly allocated GssWebsocket.
+ */
 GssWebsocket *
 gss_websocket_new (SoupServer * soup, SoupMessage * msg,
     SoupClientContext * context)
@@ -509,6 +543,18 @@ gss_websocket_new (SoupServer * soup, SoupMessage * msg,
   return client;
 }
 
+/**
+ * gss_websocket_new_single:
+ * @soup: The soup server to create this GssWebsocket* under
+ * @msg: The message to create this GssWebsocket* for
+ * @context: The context therein.
+ *
+ * Creates and returns a new GssWebsocket*
+ * which is initialized using the passed in SoupServer*,
+ * SoupMessage*, and SoupClientContext*
+ *
+ * Return value: a GssWebsocket* pointing to a newly allocated GssWebsocket.
+ */
 GssWebsocket *
 gss_websocket_new_single (SoupServer * soup, SoupMessage * msg,
     G_GNUC_UNUSED SoupClientContext * context)