[Xfce4-commits] <libxfce4ui:new-sm-client> clarify some documentation

[Brian J. Tarricone]

Updating branch refs/heads/kelnos/new-sm-client
         to be0ce0e279784b6e087b5a03b0bb38b92dd61438 (commit)
       from 38ec38a0732dd9c99395d47705d6e78930be6340 (commit)

commit be0ce0e279784b6e087b5a03b0bb38b92dd61438
Author: Brian J. Tarricone <brian at tarricone.org>
Date:   Tue Sep 15 16:19:32 2009 -0700

    clarify some documentation

 libxfce4ui/xfce-sm-client.c |   36 +++++++++++++++++++++++++++---------
 1 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/libxfce4ui/xfce-sm-client.c b/libxfce4ui/xfce-sm-client.c
index bfec8f6..35e5b66 100644
--- a/libxfce4ui/xfce-sm-client.c
+++ b/libxfce4ui/xfce-sm-client.c
@@ -1347,14 +1347,26 @@ xfce_sm_client_set_clone_restart_commands(XfceSMClient *sm_client)
  * @argc: The application's argument count
  * @argv: The application's argument vector
  *
- * Constructs a #GOptionGroup suitable for using with Glib's
- * command-line option parser, whether it is being used directly,
- * or indirectly via gtk_init_with_args() or similar.
+ * Constructs a #GOptionGroup suitable for use with Glib's
+ * command-line option parser.
  *
  * This function is a bit sneaky in that it will make a copy of
- * the program's argc and argv *before* gtk_init() etc. has a chance
- * to mess around with it, so #XfceSMClient can later construct an
- * accurate restart command.
+ * the program's argc and argv <emphasis>before</emphasis> GTK+ etc.
+ * has a chance to mess around with it, so #XfceSMClient can later
+ * construct an accurate restart command.  Instead of calling
+ * gtk_init() or gtk_init_with_args(), instead you'd do something
+ * like:
+ *
+ * <informalexample><programlisting>
+ * GOptionContext *context = g_option_context_new("");
+ * g_option_context_add_group(context, gtk_get_option_group(TRUE));
+ * g_option_context_add_group(context, xfce_sm_client_get_option_group(argc, argv);
+ * g_option_context_parse(context, &argc, &argv, NULL);
+ * </programlisting></informalexample>
+ *
+ * Error checking is omitted here for brevity, and of course you could
+ * add your app's own options with g_option_context_add_main_entries()
+ * or similar.
  *
  * Returns: A new #GOptionGroup
  **/
@@ -1662,9 +1674,11 @@ xfce_sm_client_connect(XfceSMClient *sm_client,
  *
  * Disconnects the application from the session manager.
  *
- * Note: This may not remove the application from the saved
+ * <note><para>
+ * This may not remove the application from the saved
  * session (if any) if the user later does not choose to save
  * the session when logging out.
+ * </para></note>
  *
  **/
 void
@@ -1718,8 +1732,10 @@ xfce_sm_client_is_resumed(XfceSMClient *sm_client)
  * certain action (log out, halt, reboot, etc.) or may take the
  * requested action without user intervention.
  *
- * Note: The session manager may or may not support all requested
+ * <note><para>
+ * The session manager may or may not support all requested
  * actions, and is also free to ignore the requested action.
+ * </para></note>
  **/
 void
 xfce_sm_client_request_shutdown(XfceSMClient *sm_client,
@@ -2121,8 +2137,10 @@ xfce_sm_client_get_priority(XfceSMClient *sm_client)
  * application's state.  Note that this value is only
  * guaranteed to be valid if connected to the session manager.
  *
- * Note: Instead of constructing a state filename, it is
+ * <note><para>
+ * Instead of constructing a state filename, it is
  * recommended to use xfce_sm_client_get_state_file().
+ * </para></note>
  *
  * Returns: an opaque object-owned string
  **/