Sun Jan 8 00:17:55 UTC 2006

Mensagem de log: 
revamp documentation

-----


Modified: libgksu/branches/libgksu2/ChangeLog
===================================================================

--- libgksu/branches/libgksu2/ChangeLog	2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/ChangeLog	2006-01-08 00:17:54 UTC (rev 503)
@@ -1,5 +1,10 @@
 2006-01-07  Gustavo Noronha Silva  <kov at debian.org>
 
+	* libgksu/libgksu.c, docs/*:
+	- revamp documentation; gtk-doc-style comments added to
+	  functions and some fixes to return values were made to
+	  match the docs
+
 	* configure.ac, Makefile.am, others:
 	- revamping the i18n infra-structure; mainly removing
 	  local intl/ copy and updating files

Copied: libgksu/branches/libgksu2/docs/libgksu-docs.sgml (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml)
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml	2006-01-07 17:53:42 UTC (rev 497)
+++ libgksu/branches/libgksu2/docs/libgksu-docs.sgml	2006-01-08 00:17:54 UTC (rev 503)
@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<book id="index" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <bookinfo>
+    <title>LibGKSu Reference Manual</title>
+  </bookinfo>
+
+  <chapter>
+    <title>Main Reference</title>
+    <xi:include href="xml/libgksu.xml"/>
+  </chapter>
+</book>

Copied: libgksu/branches/libgksu2/docs/libgksu-overrides.txt (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-overrides.txt)

Copied: libgksu/branches/libgksu2/docs/libgksu-sections.txt (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt)
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt	2006-01-07 17:53:42 UTC (rev 497)
+++ libgksu/branches/libgksu2/docs/libgksu-sections.txt	2006-01-08 00:17:54 UTC (rev 503)
@@ -0,0 +1,11 @@
+<SECTION>
+<FILE>libgksu</FILE>
+<TITLE>API Reference</TITLE>
+GksuError
+gksu_context_new
+gksu_context_free
+gksu_su
+gksu_su_full
+gksu_sudo
+gksu_sudo_full
+</SECTION>

Copied: libgksu/branches/libgksu2/docs/libgksu-undocumented.txt (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt)
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt	2006-01-07 17:53:42 UTC (rev 497)
+++ libgksu/branches/libgksu2/docs/libgksu-undocumented.txt	2006-01-08 00:17:54 UTC (rev 503)
@@ -0,0 +1,10 @@
+78% symbol docs coverage.
+7 symbols documented.
+0 symbols incomplete.
+2 not documented.
+
+
+GksuError
+
+
+libgksu:Short_Description

Copied: libgksu/branches/libgksu2/docs/libgksu.types (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2.types)

Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml	2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml	2006-01-08 00:17:54 UTC (rev 503)
@@ -1,13 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<book id="index" xmlns:xi="http://www.w3.org/2001/XInclude">
-  <bookinfo>
-    <title>LibGKSu Reference Manual</title>
-  </bookinfo>
-
-  <chapter>
-    <title>Main Reference</title>
-    <xi:include href="xml/gksu-context.xml"/>
-  </chapter>
-</book>

Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-overrides.txt
===================================================================

Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt	2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt	2006-01-08 00:17:54 UTC (rev 503)
@@ -1,31 +0,0 @@
-<SECTION>
-<FILE>gksu</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>gksu-context</FILE>
-<TITLE>GksuContext</TITLE>
-GksuContext
-gksu_context_new
-gksu_context_free
-gksu_context_set_user
-gksu_context_get_user
-gksu_context_set_command
-gksu_context_get_command
-gksu_context_set_password
-gksu_context_get_password
-gksu_context_set_login_shell
-gksu_context_get_login_shell
-gksu_context_set_keep_env
-gksu_context_get_keep_env
-gksu_context_set_debug
-gksu_context_get_debug
-gksu_context_set_ssh_fwd
-gksu_context_get_ssh_fwd
-gksu_context_sudo_try_need_password
-gksu_context_try_need_password
-gksu_context_run_full
-gksu_context_run
-gksu_context_sudo_run_full
-gksu_context_sudo_run
-</SECTION>

Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt	2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt	2006-01-08 00:17:54 UTC (rev 503)
@@ -1,10 +0,0 @@
-67% symbol docs coverage.
-4 symbols documented.
-0 symbols incomplete.
-2 not documented.
-
-
-gksu_context_free
-gksu_context_new
-
-

Deleted: libgksu/branches/libgksu2/docs/libgksu1.2.types
===================================================================

Modified: libgksu/branches/libgksu2/libgksu/libgksu.c
===================================================================
--- libgksu/branches/libgksu2/libgksu/libgksu.c	2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/libgksu/libgksu.c	2006-01-08 00:17:54 UTC (rev 503)
@@ -695,6 +695,15 @@
   g_free (xauth);
 }
 
+/**
+ * gksu_context_new
+ *
+ * This function should be used when creating a new #GksuContext to
+ * pass to gksu_su_full or gksu_sudo_full. The #GksuContext must be
+ * freed with gksu_context_free.
+ *
+ * Returns: a newly allocated #GksuContext
+ */
 GksuContext*
 gksu_context_new ()
 {
@@ -723,6 +732,12 @@
   return context;
 }
 
+/**
+ * gksu_context_free
+ * @context: the #GksuContext to be freed.
+ *
+ * Frees the given #GksuContext.
+ */
 void
 gksu_context_free (GksuContext *context)
 {
@@ -739,25 +754,31 @@
 }
 
 /**
- * gksu_context_run_full:
+ * gksu_su_full:
  * @context: a #GksuContext
- * @ask_pass: a #GksuAskPasswordFunc
- * @user_data: a #gpointer with user data to be passed to the
+ * @ask_pass: a #GksuAskPassFunc to be called when the lib determines
+ * requesting a password is necessary; it may be NULL, in which case
+ * the standard password request dialog will be used
+ * @ask_pass_data: a #gpointer with user data to be passed to the
  * #GksuAskPasswordFunc
- * @pass_not_needed: a #GksuPasswordNotNeededFunc
- * @pnn_user_data: a #gpointer with the user data to be passed to the
+ * @pass_not_needed: a #GksuPassNotNeededFunc that will be called
+ * when the command is being run without the need for requesting
+ * a password; it will only be called if the display-no-pass-info
+ * gconf key is enabled; NULL will have the standard dialog be shown
+ * @pass_not_needed_data: a #gpointer with the user data to be passed to the
  * #GksuPasswordNotNeededFunc
  * @error: a #GError object to be filled with the error code or NULL
  *
  * This could be considered one of the main functions in GKSu.
  * it is responsible for doing the 'user changing' magic calling
- * the #GksuAskPasswordFunc function to request a password if needed.
- * and the #GksuPasswordNotNeededFunc function if a password won't be
+ * the #GksuAskPassFunc function to request a password if needed.
+ * and the #GksuPassNotNeededFunc function if a password won't be
  * needed, so the application has the oportunity of warning the user
  * what it's doing.
- * Since 1.3.3.
  *
- * Returns: the child's error status, 0 if all went fine, -1 if failed
+ * This function uses su as backend.
+ *
+ * Returns: FALSE if all went fine, TRUE if failed
  */
 gboolean
 gksu_su_full (GksuContext *context,
@@ -784,7 +805,7 @@
       g_set_error (error, gksu_quark, GKSU_ERROR_NOCOMMAND,
 		   _("gksu_run needs a command to be run, "
 		     "none was provided."));
-      return -1;
+      return TRUE;
     }
 
   if (!context->user)
@@ -795,7 +816,7 @@
       g_set_error (error, gksu_quark, GKSU_ERROR_HELPER,
 		   _("The gksu-run-helper command was not found or "
 		     "is not executable."));
-      return -1;
+      return TRUE;
     }
 
   /*
@@ -843,7 +864,7 @@
       g_set_error (error, gksu_quark, GKSU_ERROR_FORK,
 		   _("Failed to fork new process: %s"),
 		   strerror(errno));
-      return -1;
+      return TRUE;
     }
   else
     {
@@ -986,7 +1007,7 @@
 	  if (context->debug)
 	    fprintf (stderr, "DEBUG (failed!) buf: -%s-\n", buf);
 
-	  return -1;
+	  return TRUE;
 	}
 
       FD_ZERO(&rfds);
@@ -1012,7 +1033,7 @@
 			   _("Could not read from the pipe "
 			     "with the child: %s"),
 			   strerror(errno));
-	      return -1;
+	      return TRUE;
 	    }
 
 	  if(FD_ISSET(fdpty, &rfds))
@@ -1065,6 +1086,19 @@
   return FALSE;
 }
 
+/**
+ * gksu_su
+ * @command_line: the command line that will be executed as other user
+ * @error: a #GError to be set with the error condition, if an error
+ * happens
+ *
+ * This function is a wrapper for gksu_su_run_full. It will call it
+ * without giving the callback functions, which leads to the standard
+ * ones being called. A simple #GksuContext is created to hold the
+ * user name and the command.
+ *
+ * Returns: FALSE if all went well, TRUE if an error happend.
+ */
 gboolean
 gksu_su (gchar *command_line, GError **error)
 {
@@ -1082,25 +1116,31 @@
 }
 
 /**
- * gksu_context_sudo_run_full:
+ * gksu_sudo_full:
  * @context: a #GksuContext
- * @ask_pass: a #GksuAskPasswordFunc
- * @user_data: a #gpointer with user data to be passed to the
+ * @ask_pass: a #GksuAskPassFunc to be called when the lib determines
+ * requesting a password is necessary; it may be NULL, in which case
+ * the standard password request dialog will be used
+ * @ask_pass_data: a #gpointer with user data to be passed to the
  * #GksuAskPasswordFunc
- * @pass_not_needed: a #GksuPasswordNotNeededFunc
- * @pnn_user_data: a #gpointer with the user data to be passed to the
+ * @pass_not_needed: a #GksuPassNotNeededFunc that will be called
+ * when the command is being run without the need for requesting
+ * a password; it will only be called if the display-no-pass-info
+ * gconf key is enabled; NULL will have the standard dialog be shown
+ * @pass_not_needed_data: a #gpointer with the user data to be passed to the
  * #GksuPasswordNotNeededFunc
  * @error: a #GError object to be filled with the error code or NULL
  *
  * This could be considered one of the main functions in GKSu.
  * it is responsible for doing the 'user changing' magic calling
- * the #GksuAskPasswordFunc function to request a password if needed.
- * and the #GksuPasswordNotNeededFunc function if a password won't be
+ * the #GksuAskPassFunc function to request a password if needed.
+ * and the #GksuPassNotNeededFunc function if a password won't be
  * needed, so the application has the oportunity of warning the user
  * what it's doing.
- * Since 1.3.3.
  *
- * Returns: the child's error status, 0 if all went fine, -1 if failed
+ * This function uses the sudo backend.
+ *
+ * Returns: FALSE if all went fine, TRUE if failed
  */
 gboolean
 gksu_sudo_full (GksuContext *context,
@@ -1136,7 +1176,7 @@
       g_set_error (error, gksu_quark, GKSU_ERROR_NOCOMMAND,
 		   _("gksu_sudo_run needs a command to be run, "
 		     "none was provided."));
-      return -1;
+      return TRUE;
     }
 
   if (!context->user)
@@ -1161,7 +1201,7 @@
     {
       g_set_error (error, gksu_quark, GKSU_ERROR_XAUTH,
 		   _("Unable to copy the user's Xauthorization file."));
-      return -1;
+      return TRUE;
     }
 
   /* sets XAUTHORITY */
@@ -1275,7 +1315,7 @@
 		   _("Error creating pipe: %s"),
 		   strerror(errno));
       sudo_reset_xauth (context, xauth, xauth_env);
-      return -1;
+      return TRUE;
     }
 
   if ((pipe(child_pipe)) == -1)
@@ -1284,7 +1324,7 @@
 		   _("Error creating pipe: %s"),
 		   strerror(errno));
       sudo_reset_xauth (context, xauth, xauth_env);
-      return -1;
+      return TRUE;
     }
 
   pid = fork();
@@ -1294,7 +1334,7 @@
 		   _("Failed to fork new process: %s"),
 		   strerror(errno));
       sudo_reset_xauth (context, xauth, xauth_env);
-      return -1;
+      return TRUE;
     }
   else if (pid == 0)
     {
@@ -1310,7 +1350,7 @@
 		   _("Failed to exec new process: %s"),
 		   strerror(errno));
       sudo_reset_xauth (context, xauth, xauth_env);
-      return -1;
+      return TRUE;
     }
   else
     {
@@ -1326,7 +1366,7 @@
 		       _("Error opening pipe: %s"),
 		       strerror(errno));
 	  sudo_reset_xauth (context, xauth, xauth_env);
-	  return -1;
+	  return TRUE;
 	}
 
       outfile = fdopen(child_pipe[1], "w");
@@ -1336,7 +1376,7 @@
 		       _("Error opening pipe: %s"),
 		       strerror(errno));
 	  sudo_reset_xauth (context, xauth, xauth_env);
-	  return -1;
+	  return TRUE;
 	}
 
       /*
@@ -1479,6 +1519,19 @@
   return FALSE;
 }
 
+/**
+ * gksu_sudo
+ * @command_line: the command line that will be executed as other user
+ * @error: a #GError to be set with the error condition, if an error
+ * happens
+ *
+ * This function is a wrapper for gksu_sudo_run_full. It will call it
+ * without giving the callback functions, which leads to the standard
+ * ones being called. A simple #GksuContext is created to hold the
+ * user name and the command.
+ *
+ * Returns: FALSE if all went well, TRUE if an error happend.
+ */
 gboolean
 gksu_sudo (gchar *command_line,
 	   GError **error)


